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Chapter 1. 
Overview 


INTRODUCTION 


This guide provides assistance for integrating a device driver into 
your Unisys 5000 series operating system. Information in this 
guide applies to all currently supported releases of the Unisys 
5000 Operating “ysiem for the 5000/20, 5000/30, 5000/35, 
5000/40, 5000/50, and 5000/55. 

This guide is written for programmers, analysts, and other support 
personnel. Before using this guide, you should be familiar with 
your operating system, be knowledgeable in the "C" programming 
language, and be familiar with the hardware device and its 
interface. 


CONTENTS 

The information in this guide: 

- identifies the entries required for the system files; 

- identifies the primary driver structures, 

- identifies the steps for integrating the driver into the system; 
- provides example driver programs; 


- explains driver related routines such as open, strategy, close, 
and interrupt service; and 


- describes the driver-related system calls and driver-related 
kernel calls. 
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Chapter 2. 
Device Driver Overview 


INTRODUCTION 


A device driver is the part of the kernel that controls hardware 
devices. Control includes such functions as sending control 
information, interpreting statuses, processing interrupts, writing 
data, and reading data. After a device driver is integrated into the 
kernel, it becomes a high level interface between an application 
program and a hardware device. 


Process of Program 


Hardware 


Figure 2.1. Layer Overview 


As shown in Figure 2.1, the kernel is the layer of software between 
a process or program and the actual hardware. The kernel permits 
the referencing of devices by names and permits device control 
using high level system calls. The kernel provides many other 
functions and structures for a consistent and flexible interface 
between the application and the device driver which is part of the 
kernel. 


PROGRAM/DRIVER INTERFACE OVERVIEW 


High level system calls provide the method used by a program to 
interact with a driver. The I/O system calls available to a trap to 
the kernel. The I/O system calls available to a program are open, 
close, read, write, ioctl, and Iseek. These system calls cause a 
trap to the kernel. The kernel executes code on behalf of the 
calling process. Data structures, managed by the kernel, are 
updated and a device driver function is called. 
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ELSE I SAI ESS ST EL ER 


As shown in Figure 2.2, the kernel divides I/O into two layers: 


- Device independent processing — the same code is executed 
for all devices. 


- Device dependent processing — calls are made from the device 
independent code to a device driver. 


Device Independent Kernel 


device | device | device | device 
driver | driver | driver | driver 
0 | 1 2 3 


Figure 2.2. Device Driver Interface 


The device independent interface between the kemel and the 
driver consists of a device switch table. This table specifies the 
interface routines available for the devices. 


Each device driver is referenced by its position in the device 
switch table. The first entry is referred to as device driver 0, the 
second is device driver 1, etc. A special file, representing a 
device, contains a major device number that identifies the device 
driver. The entry in the device switch table specifies the routines 
available for the selected device. This method permits the 
operating system to resolve external references (binding) between 
the device driver routines and user programs at run time. This 
provides for a structured interface while maintaining system 
flexibility. 


For example, an open system call might look like this: 
open(1); /* open device number 1, the terminal */ 
lf the relative location of the device within the device switch table 


changes, all programs using the device must be recompiled. To 
avoid this, another level of indirection is needed: 
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Device Driver Overview 


open("/dev/tty"); /* open the terminal */ 


The name /dev/tty is used to determine the major device number 
which provides the indexing into the device switch table. An entry 
in the table accesses the open routine for the device. 


NOTE: The same name could correspond to major device 
number three on one system and major device number five 
on another system. 


DEVICE DRIVER BLOCK DESCRIPTION 


Device drivers are partitioned into two segments: top end and 
bottom end. As shown in Figure 2.3, user processes access the 
upper half through system calls that reference the device switch 
tables. In effect, the top end runs as an extension of the user 
process. The top end routines don’t manipulate devices directly. 
Instead, they queue requests for data transfer and rely on routines 
in the lower half to perform the transfer. 


Except for starting the bottom end routines, the only 
communication between the top and bottom ends of the device 
driver is performed using queues and shared data. The bottom 
end routines typically run because of hardware controller interrupts 
and the kernel call timeout(k). Refer to Appendix D. 


In summary, the buffering and the interrupt processing permits 
data to be transferred between the application and the buffers at 
processor speeds, and between the device and the buffers at slow 
device speeds. 
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Figure 2.3. Driver Overview 


UP-12230 R1 


Chapier 3. 
Creating a New Kernel 


OVERVIEW 


This chapter provides the information relating to the system 
configuration files and the procedures for creating a new kernel. 
The information introduces the files required for a device driver 
and introduces other driver concepts as they relate to entries in 
the files. 


We recommend you have available a printed copy of the files 
identified in the following list to identify the driver-related entries 
for the current system configuration. Make any changes to the 
/etc/master and /kernel/sperry/cf/5.2.cf, and name.c files in your 
home directory. Consequently, the working kernel configuration 
isn’t changed. 


/etc/master 
/kernel/sperry/cf/5.2.cf 
/kernel/sperry/cf/cont.c 


/kernel/sperry/cf/univec.c 
/sys/ct 


INSTALLATION 
Here are the steps required to include a device driver into the 
kernel. Figure 3.1 identifies the primary elements involved in the 
installation procedures. 

1. Write and compile the device driver (newdevice.c). 


2. Modify the dfile (configuration file). 


3. Execute a make file that: 
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a. Executes the config program. 
b. Compiles the output of the config program. 


c. Links the kernel libraries with the new driver and the 
compiled output of the config program. 


4. Make an inode (special file) for the device. 


5. Include in the /sys/cf and /etc/master files the same 
entries made in 5.2.cf and master. 


6. Archive the newdevice.o code in the /sperry/kernel/lib2 file. 
7. Copy the file /kernel/sperry/cf/5.2.cf into the file /sys/ctf, 
so product installation through Unisys Menus System 


operates correctly for communications products: 


cp /kernel/sperry/ct/5.2.cf /sys/cf 


3-2 UP-12230 R1 


Creating a New Kernel 


Installation 


C master) C file 


(/etc/master) (/kernel/tower/cf/config.cf) 


CONFIG 
Ceonte> aan Cineswe> 
Csiario) Ceont o>) Conves.0) Gewdevice SC name.o>) 


unix 


Figure 3.1. Creating a Kernel 
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FILE/PROCEDURES DESCRIPTION 


This section describes the required files and makefile procedures. 


Purpose of the Configuration Program 


The purpose of the config program is to create two C programs 
according to a set of specifications entered in ofile (5.2.cf) file. 
The config program has two input files, master and dfile, and two 
output files, conf.c and univec.c. 


The master file describes all of the device drivers permitted on the 
system. Config uses information from the master file to carry out 
directives in the configuration file dfile. Config creates two output 
files: conf.c contains all tunable data structures including the 
block and character device switch tables; univec.c contains the 
interrupt vector table. This table provides the interrupt vector 
addresses for the hardware related interrupt service routines. 


Using Figure 3.1 as an example, the format of the config command 
is: 


/kernel/sperry/cf/conf ig -m master 5.2.cf_ 


The config(1M) command is described in the Administration 
Reference Manual. 


Master File 

The master file (an augmented version of /etc/master) contains 
information used by the config program to generate configuration 
files (see config(1M)). The master file consists of three parts: 

- Part 1 contains a line entry for each device driver. 

- Part 2 optionally contains device name aliases. 

- Part 3 contains tunable system parameters. These parameters 


don't directly relate to device drivers but can control resources 
used by device drivers. 
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A line that contains a dollar sign ($) in column 1 separates each 
part of the file. 


Master File Part 1 


A full description of the master file is found in master(4) of the 
Programming Reference Manual. Part 1 of the master file has one 
line per device driver. Each line has 10 required fields and 3 
optional fields. The following two lines are example entries for a 
disk and a console driver. 


13 


1477 214 dk stati stat2 stat3 
677 404 cr tty 


Figure 3.2. Master File Entries 
The following list describes the fields shown in Figure 3.2: 


Field 1 is the device name (8 chars. maximum); must be 
unique. This field is a key used in the first part of 
the dfile to identify this line in the master file. 


Field 2 is the interrupt vector count and naming 
conventions for the interrupt service routines. 
These are used to build the univec.c file. Refer to 
the Field 2 text for entry descriptions. 


Field 3 is the device mask. Refer to the Field 3 text for 
entry descriptions. 


Field 4 is the device mask 2. Refer to the Field 4 text for 
entry descriptions. 


Field 5 Driver (handler) prefix; defines <hp> and is used 
in the other field descriptions. 
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Field 6 Device register address space size in decimal. 
This field is the amount of Multibus address 
space needed by the device. The dkx driver has 
a value of 4 showing that 4 bytes of on-board 
registers are accessible by the disk driver. The 
crt driver has a value of 1 showing a one byte 
addressable register. This field must be non-zero 
in order to generate a <hp>_addr line in conf.ck. 
This field is used in the configuration test that 
avoids Multibus |/O address collisions. 


Field 7 is the major device number for the block device. 

Field 8 is the major device number for the character 
device. 

Field 9 is the maximum and default number of 


subdevices for the controller. 


Field 10 is the maximum bus request level. This field is 
used to limit the variable entered in field 4 of the 
Ofile part 1. 


Optional fields are the last three fields are optional. Each field 
can contain the name of a data structure needed 
by the device driver. The configuration program 
makes this declaration in the file config.c: struct 
value <hp>-value[N]. Value is the string of 
characters in field 11, 12 or 13. <hp> is the 
handler prefix. N is an integer value that is the 
same as the total number of subdevices (for 
example, number of controllers multiplied by 
subdevices per controller). In the dkx example, 
the following declaration is created: 


struct statl dk_stat1[4]; 
NOTE: Make the declaration struct stat1 
available to the conf.c file. Make the entry 


in /usr/include/sys/space.h. 
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Field 2 Description 


Here is a description of the interrupt vector count and naming 
conventions used to generate the file univec.c: 


0 No interrupts. Used for pseudo devices. 

1 Used for non-bus vectored devices to yield interrupt service 
routine (ISR) names in the format: <hp><board number>int; 
<hp> represents the handler prefix (device name). 

4 One interrupt with ISR name <hp>intr. 

§ One interrupt with ISR name <hp>Oint. 

10 Two interrupts with ISR names <hp>Oint and <hp>tint. 

12. Three interrupts with ISR names <hp>Oint through <hp>2int. 

16 Four interrupts with ISR names <hp>Oint through <hp>3int. 

20 —— Five interrupts with ISR names <hp>Oint through <hp>4int. 

24 = Six interrupts with ISR names <hp>Oint through <hp>Sint. 

28 Seven interrupts with ISR names <hp>Oint through <hp>6int. 

32  Ejght interrupts with ISR names <hp>Oint through <hp>7int. 

In the example for dkx, one bus vectored interrupt causes the 

function dkxintr to be invoked. Crt has a non-bus vectored 


interrupt that causes the function crOint for board 0, critint for 
board 1, etc. 


Field 3 Description 


This field is a device mask. The bit flags turned on by this octal 
number describe some of the characteristics of a character device 
driver. 
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01000 


00400 


00200 


00100 


00040 


00020 


00010 


00004 


00002 


Memory management resources are needed for Direct 
Memory Access (DMA). Entries in the segment map are 
reserved by setting this bit. 


In-service diagnostic routines exist. A function with the 
name <hp>diag must exist in the driver. 


A tty structure is included in the cdevsw table. The line 
discipline routines are accessed through the line switch 
table on system read and write calls instead of through 
the driver's read and write routines. 


An initialization function exists for the device with the 
name <hp>init. This routine is called when the system 
is booted. 


A power fail recovery function exists for the device with 
the name <hp>cir, called after power fail. 


An open function exists for the device with the name 
<hp>open. When a user process executes an open 
system call, this function is called. This function has an 
entry in the cdevsw table. 


A close function exists for the device with the name 
<hp>close. When the last close for a minor device is 
executed by a user process, this function is called. 
This function has an entry in the cdevsw table. 


A read function exists for the device with the name 
<hp>read. When a user process executes a read 
system call, this function is called. This function has an 
entry in the cdevsw table. 


A write function exists for the device with the name 
<hp>write. When a user process executes a write 
system call, this function is called. This function has an 
entry in the cdevsw table. 
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An ioctl function exists for the device with the name 
<hp>ioctl When a user process executes an ioctl 
system call, this function is called. This function has an 
entry in the cdevsw table. 


In Figure 3.2, the dkx driver has the following characteristics: 


01000 
00400 
00040 
00020 


Memory management resources needed for DMA. 

A dkdiag routine for inservice diagnostics exists. 
A dkclIr routine for power fail recovery exists. 

A dkopen routine exists. 

A dkclose routine exists. 

A dkread routine exists. 

A dkwrite routine exists. 

A dkioct] routine exists. 


All of the above 


The crt driver has these characteristics: 


A crdig routine for inservice diagnostics exists. 
A tty structure is to be included in cdevsw. 
Acrclr routine for power fail recovery exists. 

A cropen routine exists. 

A crclose routine exists. 

A crread routine exists. 

A crwrite routine exists. 

A crioct] routine exists. 


All of the above 


Field 4 Description 


This is the device mask 2 field. The bit flags turned on by this 
octal number describe some of the characteristics of the driver. 
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00400 The controller is non-bus vectored (for example, 
autovectored). 

00200 Only one device is permitted. 

00100 Suppress the count field in the conf.c file. 

00040 Suppress the interrupt vectors if generated. 

00020 Device is required. 

00010 Block device. 

00004 Character device. 

00002 Reserved. 

00001 Reserved. 


In Figure 3.2, the dkx driver has these characteristics: 


00200 Only one device allowed. 
00010 Block device. 
00004 Character device. 


00214 #All of the above 


The crt driver has this characteristic: 


00004 # Acharacter device. 
00400 Block device 


00404 All of the above 
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Master File Part 2 


Part 2 contains lines with 2 fields in each line. Each line defines 
an alias that can be used in the dfile. Part 2 isn’t usually used. 


Alias name of device (8 chars. maximum). 


Reference name found as the first field in part 1. 


Master File Part 3 


Part 3 entries describe the tunable system parameters that aren’t 
used by the driver but can control resources used by the driver. 


Dfile (Configuration File) 


The ofile describes the configuration of the kernel. The first part 
contains a list of driver related entries to be included in the kemel. 
The second part shows the devices used for root, pipe, and dump. 


root devname minor 
pipe devname minor 
dump devname minor 


Devname is the device name or alias as defined in the master file. 
Minor is the subdevice number (in octal). The specification of the 
swap device is also defined in the line: 
swap devname minor swaplo nswap 

Swaplo is a decimal value identifying the first block in the swap 
area, and nswap is a decimal value specifying the number of 
blocks in the swap area. 

Finally, there are a variable number of lines that can be used to 
redefine the tunable parameters set up in the master file. These 


lines have this format: 


keyword value 
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Keyword is the name found in part 3 of the master file and value is 
the numeric constant to be used. 


Dfile (Device File) Driver Entries 
The lines in Part 1 have this format: 


devname intvect baseaddar intlevel subdevs 


Devname Device name or alias defined in field 1 of the master 
file. 


Intvect Interrupt vector offset in octal. The intvect is NOT the 
vector number but is the address of the vector. If 
more than one vector is generated as configured in 
field 2 of the master file, this is the base interrupt 
vector. For autovectored devices, this octal number 
represents the device’s relative polling position in 
univec.c, and in this situation, field four must be set 
to 7. 


Baseador Base Multibus \/O address of the controller is octal. 
Must be an even number. Should be in the range 0- 
7777. 


Intlevel Multibus interrupt request level for a device. For 
autovectored devices this field must be set to 7. 


Subdevs Actual number of subdevices on the controller. 


The base address and intlevel are parameters for the driver and 
don’t affect the system. 


For example, 
dkx 460 172220 4 4 


The dkx disk driver interrupt vector location is 460. The Multibus 
base address is 172220. The interrupt level is 4. The number of 
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subdevices is 4. For example, 

*board 0 

crt 470 160000 1 8 

*board 1 

crt 480 161000 2 4 

interrupt service routine crt0int is invoked when board 0 
genesates an interrupt. The interrupt service routine crtTint is 


invoked when board 1 generates an interrupt. 


There are 12 variables (number of minor devices) defined for each 
device unless that feature has been disabled by the master file. 


- Multibus base addresses 16000 and 161000. 


- Positions 1 and 2 are used by the boards on the autovectored 
poll lists. 


- The first board has 8 sub-devices and the second board has 4 
sub-devices. 


The following two lines are contained in the conf.c file: 


int dk_cnt = 4; 
int cr_cnt = 12; 


The total number of subdevices is generated for the crt driver. 


UP-12230 R1 | 3-13 


Chapter 3 


SS EE ET a 


The following lines would also be generated: 


int dk_addr[]= 
{172220, 4, 460}; 

int cr_addr[{]= 
{160000, 1, 470, 
161000, 2, 480}; 


NOTE: These are arrays that contain a line for each 
controller. 


Miscellaneous Files | 


Miscellaneous files required for creating a kernel are: 


newdevice.c The newdevice.c file contains the source code 
routines for the new device driver. This file 
typically resides in the user’s home directory. 


start.o For the 5000/20 and 5000/40, the start.o file 
relocates the kernel code to a logical starting 
address of 108000H following a bootload. For the 
5000/30, 5000/35, 5000/50, 5000/55 and 32-bit 
5000/40, the siart.o file relocates the kernel code 
to a logical starting address of EQ0000H following 
a bootload. This file resides in /kernel/sperry/ml. 
This must be the first file in the /d(1) command, 
used to link the kernel. 


linesw.o The linesw.o file is a switch table with line entries 
that define the line discipline routines (LDRs) that 
are available for character devices. Each line is 
indexed by an LDR number. LDR 0 is the only line 
in the table and identifies the line discipline 
routines for tty type terminals. This file resides in 
/kernel/sperry/linesw.c. 
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name.c The name.c file contains the user defined header 
information output to the console when the kernel 
is booted and includes system name, node name, 
release, version, and machine name. This file 
resides in /kernel/sperry/cf/name.c. 


lib0-lib9 These files are the kernel libraries that reside in 
the /kernel/sperry directory. 


Makefile Procedures 


The procedures for creating a new kernel are included in the 
following makefile. The make(1) command is used to execute the 
file. 


In this example, the makefile is in the user’s home directory and 
the format for the make command is: 


make -f Makefile unix 


/* The Makefile */ 
test = newdevice.o 


# define for name.o so boot up console messages are printed out 
correctly 
SYS = UTS V 
VER = yours 
NODE = U5000 
REL = 1R1 
f MACH = 68010 for 5000/20 and 5000/40 
f MACH = 68020 for 5000/30, 5000/35, 5000/50, 5000/55 and 32-bit 5000/40 
MACH = 68010 
DEFS = -DSYS="\"$(SYS)\"" \ 
-DVER="\"$(VER)\"" \ 
-DNODE="\"$(NODE)\"” \ 
-DREL="\"$(REL)\"" \ 


-DMACH="\"$(MACH)\"" 
AS = as 
cc . ce 


# RELOC = 108000 for 5000/20 and 5000/40 

f RELOC = £00000 for 5000/30, 5000/35, 5000/50, 5000/55, and 32-bit 5000/40: 
RELOC = 108000 

CFLAGS - -K -I. $(INCRT) 
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LFLAGS = eR $(RELOC) -N -e susentry 


LIBS = /kernel/sperry 
INCRT = /usr/ include 


unix: conf.o name.o univec.o $(LIBS)/cf/1inesw.o$(LIBS)/11b[0-9] $(test) 
1d $(LFLAGS) /kernel/sperry/m1/start.o\ 
univec.o\ 
conf .o\ 
name.0\ 
$(LIBS)/cf/1inesw.o\ 
\ 
$(test)\ 
$(LIBS)/11b[0-9)\ 
$(LIBS)/11b3\ 


-o unix\ 
2> undefs 


name.o: $(INCRT)/sys/utsname.h 
$(CC) $(CFLAGS) $(DEFS) -c name.c 


conf.o: conf.c newdevice.h 
univec.o: univec.c 


univec.c: 5.2.cf master 
config -m master 5.2.cf 


conf.c: 5.2.cf master 
config -m master 5.2.cf 


newdevice.0: newdevice.c newdevice.h 


Archiving the Driver 

After compiling and testing the new kernel, the driver must be 
archived in the kernel. The driver typically resides in 
/kernel/sperry/lib2. The command for archiving is: 


cd /kernel/sperry 


ar rv lib2 newdevice.o 
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The ar(1) command is described in the Administration Reference 
Manual. Following the archival, a new kernel can be created using 
the standard script: 


/menu/script/makeos.sh save 


Making an Inode 
The mknod command adds the driver inode to the system. 


/etc/mknod /dev/name [cor b] major minor 


Name is the name of the device, c or b specifies the type of device 
(character or block), major is the major number, and minor is the 
minor number. Major and minor entries are the same as the entries 
in the master file. 


System File Entries 


The /etc/master and /sys/cf system files must be manually 
updated to include the same new entries that are made in 5.2.cf 
and master. These two system files are used by the System 
Administrator menu; updating operating system software menu 
selection for building a new kernel. If the entries are not in the two 
files, the driver functions are not included during a system 
administrator's update of the operating system. 
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OVERVIEW 


A device driver performs I/O based on the request of a process. 
Most I/O in the operating system Is interrupt driven. After a 
process requests I/O, the driver makes a request to suspend the 
execution of the calling process until the I/O is completed. After 
the suspension of a process, another process can start executing. 
Process management controls the starting and suspending of 
processes. 


PROCESS DEFINITION 
As shown in Figure 4.1, a process consists of a program (user 
code) and the kernel. When the program performs a system call, 


the kernel executes code for the process. 


Process 


Figure 4.1. Process Components 
An important function of the kernel is to manipulate processes. 
The device driver portion of the kernel plays a major role in 
controlling processes. 


In a multiprocessing system, these conditions describe the 
relationship between a process and the processor (CPU): 


- Many processes typically compete for the processor. 
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- Only one process may actually be using the processor at one 
time. 


- All processes assume exclusive use of the processor. 


At any time, the highest priority process eligible for CPU service is 
executing. Among processes with equal priority, scheduling is 
round-robin, where processes are selected one after another so 
that all members of the set have an opportunity to execute before 
any member has a second opportunity. The currently active 
process makes requests for services, such as reading data from a 
file or writing to a terminal. These requests cause kernel code to 
be executed. 


Figure 4.2 shows how a processor might be shared between three 
processes. Each dash represents a time unit. 


A process may lose the processor for several different reasons, 
such as expiration of its time slice, request for a service that can't 
be immediately satisfied, a more important process being 
activated, etc. Therefore, each process does not receive an equal 
time slice. 


PROCESS STATES 


During its existence, a process goes through a series of discrete 
states - ACTIVE, READY, and SLEEP: 


- The currently executing process is in the ACTIVE state. Only 
one process can be in the ACTIVE state at any one time. 


- Any process ready to use the processor is in the READY state. 
Many processes can be in the READY state at the same time. 
Processes wait on a READY list to compete for the processor. 


- Any process waiting for some condition to be satisfied is in the 
SLEEP state. For example, a process may be asleep waiting 
for a character to be entered on a terminal. Many processes 
can be in the SLEEP state. 
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Figure 4.2. Process Timesharing 
When a process changes states, it makes a state transition. Figure 
4.3 describes the state transitions. 
A device driver can cause a transition between ACTIVE and SLEEP 
(when the I/O starts) or SLEEP and READY (when the I/O 
completes). The sleep function (in the kernel) puts the currently 


executing process to sleep. The function has this format: 


sleep(event, pri) 
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Figure 4.3. Partial State Diagram 


event A unique number identifying the reason a process was 
put to sleep. The process is sleeping for an event. 
Processes can be asleep waiting for a timer to expire, a 
terminal key to be pressed, a buffer to be filled, etc. 
Normally, the event is the address of a data structure; for 
example, the address of the buffer to be filled. 


pri The priority (relative importance) the process obtains after 
it “wakes up". Keep in mind that priority is not related to 
the splx() (refer to Appendix D) processor priority kernel 
call. 


The wakeup function activates all processes waiting for a specific 
event (causes a transition from the SLEEP state to the READY 
state). The wakeup function has this format: 


wakeup(event) 
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event The event that has occurred. 


SLEEP AND WAKEUP 


There are four concepts a device driver must consider when it puts 
processes to sleep and wakes them up: 


- The sleep can be thought of as a suspension until some 
condition is met. 


- For each sleep there has to be a wakeup. 


- The driver can put more than one process to sleep on the 
same condition. Therefore, after returning from a sleep, the 
condition must be examined to be sure that it has been 
satisfied. If the condition isn’t satisfied, the process should be 
put back to sleep. 


For example, two processes could be asleep waiting to receive 
a message when it is delivered. When the message is 
delivered, wakeup is called and both processes are moved to 
the READY list. The first process to execute may receive the 
message. When the second process finally gets to execute, 
the driver needs to realize that the message has been received 
and should put the process back to sleep. 


- There is overhead involved in a wakeup, so it should only be 
called if there is a process sleeping. 


Device drivers need a method to determine if certain conditions 
are met when processing a request. For example, the device 
driver needs to check if a process is sleeping for I/O before 
issuing a wakeup. Device drivers normally use binary flags in a 
"state variable" to represent required conditions. 


Typically, these flags are stored as single bits in an integer. For 
example: 
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- Wakeup can be called from the top half or the bottom half of the 
driver. 


- Sleep can only be called from the top half of the driver. 


SS 
#def ine CONDITION X 0x01 
fdefine SLEEP_X 0x02 
short state; 
To set a flag, a binary OR is used to turn on the CONDITION_X bit 
in state: 
state |= CONDITION X;/* state = state | CONDITION_X */ 
To test a flag, the binary AND is used: 
if (state & CONDITION_X) 
/* CONDITION_X is true */ 
else 
/* CONDITION X is false */ 
To clear a flag, the binary AND is used with NOT to turn off the bit 
representing CONDITION_X: 
state &= ~(CONDITION X); 
Device drivers generally need flags for at least two conditions: 
CONDITION_X Condition X must be satisfied before a processes 
execution can continue. The process is put to 
sleep until the condition is satisfied. 
NOTE: This condition may not actually be a 
flag. For example, a process can sleep until 
a list has a certain number of characters 
instead of just empty or full. 
SLEEP _X One or more processes are sleeping. The routine dl 


satisfying CONDITION_X only issues a wakeup if 
SLEEP X is true. 
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Driver code executed for a process put to sleep includes: 


while (state & CONDITION X) /* while cond. is not satisfied */ 
state {= SLEEP X; /* mark as sleeping */ 
sleep(&buffer, PRIORITY); /* wait for buffer to be filled */ 
} 


copy-buf fer-to-user-space; 


Driver code executed to move a process to the READY state 
includes: 


something = goodstuff; /* the buffer is filled */ 
state &= “CONDITION_X; /* condition is therefore satisfied */ 
if (state & ~SLEEP_X) /* is anyone sleeping? */ 


{ 
state k= ~SLEEP_X; /* no longer sleeping */ 
wakeup(&buffer); /* so wake those waiting */ 
} 

CRITICAL SECTIONS 


In some cases, it is possible for a driver's top end code to be 
interrupted by its bottom end code. In order to prevent shared 
data areas from being corrupted in this case, the top end typically 
invokes a Set Priority Level function spl) (refer to Appendix D) to 
exclude hardware controller or timeout(k) interrupts. After leaving 
a critical section of code, the top end restores the priority using 


splx(). 
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Chapter 5. 
A Pseudo Device Driver 


OVERVIEW 


This chapter describes an exampie device driver, sd, that 
implements the basic functions required by all device drivers 


The sd device driv ar is a pseudo character device driver; pseudo 
means that no hardware is actually being controlled. Each minor 
device is a mailbox that unrelated processes can use to send or 
receive messages, Each minor device (sd0,sd1, ... sdn) has the 
capacity to hold one message. 


Figure 5.1 illustrates process 0 and process 1 communicating 
through the mailbox represented by minor device sd0. 


Figure 5.1. Driver Block Description 


Figure 5.2 shows that Proc 0 communicates with Proc 1 through 
tne sd device driver. Requests to the sd device driver are made 
using system calls. The system calis used by the sd device driver 
are: 
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open request access to sd. 

close finished with sd. 

read retrieve a message from the mailbox. 
write store a message in the mailbox. 

ioctl sd control command. 


SDRSTATE Return (read) the state of the mailbox. 


SDWSTATE Set (write) the state of the mailbox. 


kernel 


sd device driver 


Figure 5.2. Process Communication 


1/O System Control Flow 


Figure 5.3 shows the control flow for the sd character device 
driver. Each system call used by a program corresponds to a call 
to the device driver. The entry points to the driver are the system 
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call names preceded by the handler prefix for the device. The 
handler prefix is a short acronym that uniquely identifies each 


driver. 


user 
kernel 


sdopen | sdclose | sdread | sdwrite | sdioctl 


sd device driver 


Figure 5.3. Control Flow 


Device Identification 


There are many device drivers included in the kernel. The open(2) 
system call identifies which device driver is to be accessed. 
Because all devices are accessed as if they were files, an inode 
must exist for each device. 


An inode has a mode field (Figure 5.4) that contains bit flags. The 
bit identified by the octal number 020000 is ON if the inode 
represents a block device. The bits identified by 060000 are ON if 
the inode represents a character device. If either of these bits is 
on, the inode is called a "device node." 


Device nodes have two numbers instead of block pointers in the 
inode. 


- The major device driver number identifies the driver. For 
example, the HPSIO driver is identified by major device number 
71: 
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- The minor or "sub device" number identifies a specific device. 
For example, /dev/ittyO7 has the minor device number 1, 
/dev/tty02 has the minor device number 2, etc. 


normal inode block pointers other stuff 


device node mode major | 


minor | unused |other stuff 


Figure 5.4. Device Node 


Device Creation - /etc/mknod 


Device nodes are created by the command /etc/mknod. The 
format of the command is: 


/etc/mknod name c | b major minor 


The names typically reside in the /dev directory. The type of 
device is identified by c (character) or b (block). For example: 


# /etc/mknod /dev/sd c 18 0 
The character device node /dev/sd has major number 18 and 
minor number 0. Major number 18 was used because 18 is not 


used for any other device driver in the kernel. The /s -¢ command 
displays major and minor information for device nodes. 
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$ Is -1 /dev/sd 


Crw-rw-rw- 


1 root 18, 0O Aug 20 16:15 /dev/sd 


minor device number 
major device number 


character special file 
(device node) 


Figure 5.5. Device Node Display 


Character Device Switch Table 


The character device switch table (cdevsw) contained in the kernel 
defines the location of all character device driver entry points. This 
table is indexed by the major device number. The cdevsw table is 
defined in the file /usr/include/sys/cont.h. 


/* 


* Character device switch. 


*/ 

struct cdevsw { 
int (*d_open)(); 
int (*d_close)(); 
int (*d_read)(); 
int (*d_write)(); 
int (*d_foctl)(); 
struct tty *d_ttys; 


}; 


extern struct cdevsw cdevsw[]; 


The table values are defined in the file conf.c. 


struct cdevsw cdevsw[] = { 


/* 0*/ necopen, necclose, necread, necwrite, necioct], nec_tty, 
/* 1*/ nulldev, nulldev, msread, write, nodev, 0, 
[* 2*/ conopen, nulldev, conread, conwrite, conioct], 0, 
[* 3*/ nodev, nodev, nodev, nodev, nodev, 0, 
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syopen, 
mpcopen, 
nodev, 
wdopen, 
tpopen, 
nodev, 
hpmopen, 
hpopen, 
nodev, 
nodev, 
so_open, 
nt_open, 
nodev, 
nodev, 
sdopen, 
nodev, 
dtopen, 
nulldev, 
nodev, 
nodev, 
nodev, 
erropen, 
nodev, 
nulidev, 


NOTE: Any line entry in the conf.c file with all nodev 
and 0 is available for use. Nodev mean no device driver 


nul ldev, 
mpcclose, 
nodev, 
wdc lose, 
tpclose, 
nodev, 
nulldev, 
hpclose, 
nodev, 
nodev, 
so_close, 
nt_close, 
nodev, 
nodev, 
sdclose, 
nodev, 
dtclose, 
nulldev, 
nodev, 
nodev, 
nodev, 
errclose, 
nodev, 
nul idev, 


syread, 
mpcread, 
nodev, 
wdread, 
tpread, 
nodev, 
nodev, 
hpread, 
nodev, 
nodev, 
so_read, 
nt_read, 
nodev, 
nodev, 
sdread, 
nodev, 
dtread, 
cdtread, 
nodev, 
nodev, 
nodev, 
errread, 
nodev, 
nodev, 


sywrite, 
mpcwr ite, 
nodev, 
wdwrite, 
tpwrite, 
nodev, 
hpmwrite, 
hpwrite, 
nodev, 
nodev, 
so_write, 
nt_write, 
nodev, 
nodev, 
sdwrite, 
nodev, 
dtwrite, 
cdtwrite, 
nodev, 
nodev, 
nodev, 
nodev, 
nodev, 
nodev, 


syioctl, 
mpcioctl, 
nodev, 
wdioctl, 
tpioctl, 
nodev, 
hpmioctl, 
hpioctl, 
nodev, 
nodev, 
so_foctl, 
nt_ioctl, 
nodev, 
nodev, 
sdioctl, 
nodev, 
dtioctl, 
cdtioctl, 
nodev, 
nodev, 
nodev, 
nodev, 
nodev, 
nodev, 


is configured with that major number. Nulldev means a 
device driver is configured but has no entry point. 
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cdevsw 


Pa 
ean 
eee 
20 | | | | 
Eee 
bee 
Zee 


device drivers 


sd driver 
(entry 18) 


Figure 5.6. The cdevsw Entries 


System Include Files 


The kernel has many internal structures and constants that can be 
used by a device driver. These items are defined in include files 
in the directory /usr/include/sys. Here are a few of the most 
often-used include files: 


types.h - basic data types such as uint for unsigned 
int and dev_t for device type. 
param.h - basic kernel parameters such as table sizes 
sysmacros.h - C preprocessor macros such as major(d) 
and minor(d) 
but.h - buffer and queue header structures. 
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iobuf.h - queue header structures used by block 
device drivers. 
user.h - user structure definition. 


proc.h - process table definition. wd 
signal.h - structures used to send software signals to 
processes. 


errno.h - standard errors defined in the Programming 
Reference Manual. 
dir.h - directory structure. 


NOTE: The include files must be specified for the driver. 


sd - Declarations 


The primary variables and structures are: 


sd_cnt: 
extern int sd_cnt 
Ww 
Shows the number of minor devices permitted. This 
number is a configuration parameter independent of the 
device driver. 
sd_sdinfo: 
extern struct sdinfo sd_sdinfo[] 
Defines a mailbox and contains a mailbox for each minor 
device. The length of sd-sdinfo array is sd_cnt. Refer to 
Figure 5.7. 
The structure sd_sdinfo and the variable sd_cnt are both defined 
in the file conf.c created by config (1M) during the the kernel 
generation process. 
Ww 
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lo’ sie sdinfo sdinfo sd__sdinio 


int state: 
int count; 
oe buf [SDSIZE}; 


sd__sdinfo(0} 


sd__sdinfo(1] 


sd__sdinfo([2] 
on 
sd__sdinfo[n} 
nis sd_ocnt-1 
Figure 5.7. Mailbox Structure 
o, Device Driver Open and Close Routine 


The device driver open and close routines are defined as foliows: 
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sdopen(minor_d, flag) 


dev_tminor_d; /* minor device number */ 
int flag; /* the 4 least sig. bits are defined 
in file.h */ 


sdclose(minor_d) 
dev_tminor_d; /* minor device number */ 


The device driver open and close routines are called using the 
cdevsw table. The minor device number is passed to these 
routines to identify the sub device. 


The flag in sdopen comes from the value given in the application 
program (system) open call. For example: 


main() 
{ 
open("/dev/sd", 2); 
} 


The value of flag comes from the second argument (value is 2). 
The major number identifies the device driver and is not passed as 
a parameter. 


sd Definition - sdopen 

int sdopen(minor_d, flag); 
dev_t minor_d; 

int flag; 

WHERE 

minor_d minor device number. 


flag defines open mode as in /usr/include/sys/tile.h 


FREAD _ read only access was requested 
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FWRITE write only access was requested 


FNDELAY non blocking (permits configuration ioctl’s to 
take place before read or write) 


FAPPEND all writes will append to end of file (device) 
FSYNC permits synchronous writes (non-overlapped) 


FEXEL permits exclusive use (locks out other users 
from opening the device) 


DESCRIPTION 


The minor device number is validated. If the system call 
open("/dev/sd0", 2) is made, the value of flag is 3. The argument 
of 2 in the open system call represents O_RDWR (See 
/usr/include/fent.h.) The flag value comes from the values for 
FREAD and FWRITE in /usr/include/sys/file.h. 


FAILURE CONDITIONS 


Invalid device [ENXIO] minor number is out of range. 


Related Include Files 


The file fent.h is used within the program. The file file.h is used by 
the device driver. The definition of most flags is the same. In 
filesh, FREAD and FWRITE are bit flags. In fcni.h O RDONLY, 
O_WRONLY, and O_RDRW are used. All of the O_ flags in fentl.h 
can be used by an application and interpreted by the driver and 
don't affect the driver independent kernel. 


/usr/include/fent.h 


fident "@(#)head:fcntl.h Lake’ 

/* Flag values accessible to open(2) and fcnti(2) */ 

/* (The first three can only be set by open) */ 

#define O_RDONLY 0 

#define  O_WRONLY 1 

fdefine 0 _RDWR 2 

fdefine O_NDELAY 04 /* Non-blocking I/0 */ 

#define | O_APPEND 010 /* append (writes guaranteed at the end) */ 
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#define O_SYNC 020 /* synchronous write option */ 


/* Flag values accessible only to open(2) */ 

#define O_CREAT  00400/* open with file create (uses third open arg)*/ 
#define  O.TRUNC 01000/* open with truncation */ 

#define 0 EXCL 02000 /* exclusive open */ 


/* fenti(2) requests */ 
#define F_DUPFD 
fdefine F_GETFD 
define F_SETFD 
fdefine F_GETFL 
Adefine F_SETFL 


/* Duplicate fildes */ 

/* Get fildes flags */ 

/* Set fildes flags */ 

/* Get file flags */ 

/* Set file flags */ 
@define F_GETLK /* Get file lock */ 

fdefine F_SETLK /* Set fille lock */ 

@define F SETLMH 7 /* Set file lock and weit */ 


Rw > we WY & & 


/* file segment locking set data type - information passed to system by user °*/ 
struct flock { 
short 1_ type; 
short 1_whence; 
long 1 start; 
Yona 1_len; /* len © 0 means until end of file */ 
short lu sysid; 
short upid; 
}: 


/* file segment locking types */ 
/* Read lock */ 
#define FRAC Ol 
/* Write lock */ 
@define F_WRLEX 02 
/* Remove lock(s) */ 
@define F UNL 03 


/usr/include/sys/file.h 


/* Sie */ 
/* a(e)file.b 6.2 */ 

/* 

* One file structure is allocated for each open/creat/pipe call. 
* Main use 1s to hold the read/write pointer associated with 

* each open file. 

| 

struct file 


char f_flag; 
ent_tf_count; /* reference count */ 


union { 
struct inode *f_uinode;  /* pointer to inode structure */ 
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Struct file *f_unext; /* next entry in freelist */ 


} f_up; 
union { 
off_tf_off; /* read/write character pointer */ 
} f_un; 
}; 
fdefine f_inode f_up.f_uinode 
#define f_next f_up.f_unext 


fdefine f_offset f_un.f_off 


extern struct file file[]; /* The file table itself */ 
extern struct file *ffreelist; /* Head of freelist pool */ 


/* flags */ 

fdefine FOPEN(-1) 
#define | FREADOOOO] 
fdefine FWRITE 00002 
#define FNDELAY 00004 
#define FAPPEND 00010 
#define | FSYNC 00020 
#define | FMASK 00377 


/* open only modes */ 
#define FCREAT 00400 
#define FTRUNC 01000 
fdefine | FEXCL02000 


sdopen Listing 


/* weer ccee cere cease cee rweceecoesewccccecosacocccecesaccesouscoucccoeceo 
* sdopen -- validate the minor device number. 
Cede SSSecececesoucooenesseeounseonsseeeeencsoewcecesneesnceseeesso 
*/ 
void sdopen(minor_d, flag) 
dev_t minor_d; /* minor device number */ 
int flag; /* flag indicating read/write */ 
{ 
if (minor_d >= sd_cnt) 
{ 
u.u_error = ENXIO; 
return; 
: 
} 
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sdopen is called using the cdevsw table and validates the minor 
number. 


sd Definition - sdclose 


int sdclose(minor_d); 
dev_t minor_d; 


WHERE 

minor_d minor device number. 

DESCRIPTION 

Does nothing. The driver’s close routine is only called on the last 
close to an open device. If two processes have a device open 
simultaneously, the close routine is only called after both 
processes Call c/ose. 


FAILURE CONDITIONS 


None 


sdclose Listing 


| 
void sdclose(minor_d) 
dev_t winor_d; /* minor device number */ 


{ 
print2("sdclose\n"); 
} 


Accessing User Memory Space (ioctl Functions) 
Programs can specify invalid addresses when making requests 


from the kernel. To protect the kernel from program errors, data 
is NEVER copied directly from kernel to user space. 
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Data can be copied from kernel space to user space using special 

kernel functions. Two of these functions are suword(k) and 

fuword(k). 

suword Set user word. Transfer one integer value (four bytes) 
from kernel space to user space. If suword fails because 
of a bad user address, the value -1 is returned. 

fuword Fetch user word. Transfer one integer value (four bytes) 


from user space to kernel space. The return value of -1 
indicates an error. 


Examples: 


if (suword(wordptr, 12) == -1) /* move 12 to users buffer */ 
{ seo Ovror ..- } 


if ((val = fuword(wordptr) == -1) /* retrieve an integer */ 
{ .e. error ... } 


For more information on accessing user space, see: fubyte (k), fuword 
(k), fustr (k), subyte (k), susir (k), copyin (k), copyout (k), iomove (k). 


sd Definition - sdioctl 

int sdioctl(minor_d, cmd, arg); 
dev_t minor_d; 

int cmd; 

int * arg; 

WHERE 

minor_od minor device number. 


cmd command or function to perform. 


arg pointer to argument defining a parameter block. 
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DESCRIPTION 

These commands are available: 

SDRSTATE Copy state of mailbox to the user’s argument. 
SDWSTATE Copy user’s argument to the state of the mailbox. 
FAILURE CONDITIONS 


EINVAL is returned if an invalid command is requested. If arg is 
not a valid address within user space, a bus error or addressing 
error occurs and a panic trap is invoked and EINVAL can not be 
returned. 


Example Use of SDIOCTL 


#include <fcntl.h> 
#include </usr/acct/yours/sd/sd.h> 
main() 
{ 
int fd; /* file descriptor */ 
int state; /* result of sdioct! */ 


fd = open("/dev/sd1", O_RDWR); 
foctl(fd, SORSTATE, &state); 
printf("value of state variable is %x\n", state); 


} 


NOTE: The driver manipulates the variables associated with 
sd_sdinfo (see sdioct/). 
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sd__sdinfo 
— sdp 
sd_ sdinfo[0] = sdp-—— state 
sd__sdinfo[1] 
sd__sdinfo(2] 
sd__sdinfo[n) 


nis sd_cnt- 1 


Figure 5.8. Functions of joct] 


sdiocti Listing 


[tewwewcecccnncnscccceces Coccccowccenesccncuccensevsuseseeseccoosseces 
* sdioct] -+ perform the contro] functions 
[PrrTTTT TT ttt PTTT TTI TTT TTT titty eee 
a 
void sdioct}(minor_d, cmd, arg) 

dev_t minor d; 


UP-12230 R1 5-17 


Chapter 5 


int cmd; 
int * arg; 


struct sdinfo * sdp; 


sdp = &sd_sdinfo[minor_d]; 
switch (cmd) 


{ 

case(SDRSTATE): 
suword(arg, sdp->state); 
break; 

case(SDWSTATE): 
sdp->state = fuword(arg); 
break; 

default: 
u.u_error = EINVAL; 
return; 


PROCESS MANAGEMENT, U STRUCTURE 


Information needed when a process is executing is stored in the 
System Data Segment. This data segment is a user structure as 
defined in the file /usr/include/sys/user.h. 


There is a user structure for every process. Only the user 
structure for the currently executing process is mapped into kernel 
space. When executing kernel code, the variable u is used to 
access the user structure. An interrupt service routine (ISR) must 
not use this structure because the ISR cannot predict which 
process is going to be active when the interrupt occurs. 


Some u structure fields used for communicating with a device 
driver are: 


u.u_base address of user's buffer 


u.u_count number of bytes to be transferred between user and 
kernel space. 
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u.u_ offset byte offset into the file or device to be accessed. 


a u.u_error set by the driver to a non zero value to indicate an 
error. 


lf u.u_error is set to a non-zero value, a -1 is returned from the 
system call to the user program. If u.u_error is not set, a zero is 
returned from the open, close, seek, and ioctl function calls. The 
number of bytes read is returned from the read and write system 
calls. For example, if a user program makes a read system call as 
follows: 


main() 


{ 
read (fd, buf, 10); 


} 


The device driver is called with the following values in the u 
- structure Set: 


u.u_base = buf; 
u.u_count = 10; 


The device driver may have code as follows: 


sdread(minor_d) 
dev_tminor_d; /* minor device number */ 


{ 


for(; u.u_count; --u.u_count, ++u.u_base) 


{ 


c = read_device(); 
if (c == -1) 
Lm» break; 


subyte(u.u_base, Cc); 


a 


UP-12230 R1 9-19 


Chapter 5 


lf the device driver read routine changes the value of u.u_count to 
2, the value returned from the user's read call is 8. 


Data Movement and the U Structure (Passc Cpass) 


Device drivers may need to move a string of characters to user 
space. The function call subyte(u_base, string[i]) copies one byte 
from kernel space to user space. The following fields in the u 
structure need to be updated after subyte is used: 


u_count decremented 

u_offset incremented 

u_base incremented 

A single function passc(c) moves a character into user space and 
adjusts the three fields in the u structure. passc(c) returns -1 
when the last character the user requested has been copied. For 
example, when u_count is decremented to 0. passc(c) also 
returns -1 if an error occurs and sets u_error = EFAULT. 

The function cpass( returns a byte fetched from user space and 


updates the same three parameters. cpass() returns -1 when 
u_count signals that all characters have been read (u_count is 0). 


Error Codes 

A driver's top end reports errors by setting the u.u_error byte. 
Standard error numbers are taken from the 
/usr/include/sys/errno.h file list. \f a driver must define unique 
error codes, beyond those in the standard list, the following items 
must be considered. 

- Compatibility with existing applications is not a requirement. 


- Emulation of existing devices is not a requirement. 
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- Use of perror(3C) is not a requirement. 


Driver errors detected during bottom end processing are kept in 
the driver's private data area until they can be transferred via a top 
end function. 


sd Definition - sdread 


int sdread(minor_d); 
dev_t minor_d; 


WHERE 
minor_d_ is the minor device number. 
DESCRIPTION 


Attempts to read a message from the mailbox. If there is no 
message, sleeps until there is a message. The flag SOMESSAGE 
signals there is a message to read. The flag SDRSLP signals that 
the process that called read is asleep. The flag SDWSLP signals 
that the process that called write is asleep. After the message has 
been read, wakeup any processes that are sleeping, (waiting for 
the mailbox to become empty.) 


FAILURE CONDITIONS 


None 


sdread Listing 


* sdread -- read a message from the buffer. 

* sleep if there is no message in the buffer 

* transfer the message to user space 

* wakeup any write processes waiting for an empty buffer 


sf 4 
yoid sdread(minor_d) 
dev_t minor_d; 


{ 
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struct sdinfo * sdp; /* pointer to minor device info structure */ 
char * strp; /* pointer to message in buf */ 


sdp = &sd_sdinfo{minor_d); 
strp = sdp->buf; 


while (1(sdp->state & SDMESSAGE)) /* sleep if no message in buf */ 


{ 
sdp->state |= SDRSLP; /* mark as sleeping */ 
sleep(sdrsip(sdp), SOPRI); /* sleep on address */ 
} 
while (sdp->count--) /* transfer message to user space */ 
if(passc(*strp++) == -1) 
break ; 
sdp->state &= “SDMESSAGE ; /* there is no longer a message */ 
if (sdp->state & SDWSLP) /* if there are processes sleeping */ 
{ 
sdp->state &= “SDWSLP; /* clear sleep state */ 
wakeup(sdws 1p(sdp)); /* wakeup all processes sleeping */ 
} 


sd Definition - sdwrite 


int sdwrite(minor_ qd); 
dev_t minor_d; 


WHERE 

minor_d_ is the minor device number. 

DESCRIPTION 

Attempts to write a message to the mailbox. If there is a message 
in the mailbox, sleeps until the message is removed. Once the 
message has been written, wakeup any processes that are 
sleeping (waiting for the mailbox to become full). 


FAILURE CONDITIONS 


None 
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sdwrite Listing 


* 


J 


* sdwrite -- write a message into the buffer. 


sleep if there is a message in the buffer 
transfer the message from user space 
wakeup any read processes waiting for an empty buffer 


void sdwrite(minor_d) 


int minor_d; 


{ 

struct sdinfo * sdp; /* pointer to minor device info structure */ 
char * strp; /* pointer to message in buf */ 

int 4; /* counter */ 

int c; /* character moved from user space */ 


sdp = &sd_sdinfo[minor_d]; 
strp = sdp->buf; 


while (sdp->state & SDMESSAGE) /* sleep if message in buf */ 
{ 
sdp->state |= SDWSLP; /* mark as sleeping */ 
sleep(sdwslp(sdp), SDPRI); /* sleep on address */ 
} 


sdp->count = 0; 
for (f=SDSIZE; i--; sdp->count++) 
if((c = cpass()) == -1) 


= 


* transfer message from user space */ 


break; 
else 
*strpt+ = ¢; 
sdp->state {= SDMESSAGE; /* there is a message in the buffer */ 
if (sdp->state & SDRSLP) /* if there are processes sleeping */ 
{ 
sdp->state &= ~SDWSLP; /* clear sleep state */ 
wakeup(sdrs}p(sdp)); /* wakeup all processes sleeping */ 
} 


a CREATING THE NEW KERNEL 


The following lines in the master file describe the sd driver: 
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Pat 2[ 3[4] 5 | 6 { 7mb | smc | 9 | 10 
rsd Tofaz{[4{sdfojo | 6 | 8} 0 


The following line in the ofile for the config program describes the 
sd driver: 


The makefile listed in the previous chapter can be used to create 
the kernel. 


These commands create the device nodes: 


# /etc/mknod /dev/sd0 c 18 0 
# /etc/mknod /dev/sd1 c 18 7 
# /etc/mknod /dev/sd2 c 18 2 
# /etc/mknod /dev/sd3 c 18 3 
# /etc/mknod /dev/sd4 c 18 4 
# /etc/mknod /dev/sd5 c 185 
# /etc/mknod /dev/sd6 c 18 6 
# /etc/mknod /dev/sd7 c 187 


This program writes "hi" to mailbox /dev/sd0: 


nain() 
{ 
int fd; 
fd = open("/dev/sd0", 2); 
write(fd, "hi", 2); 
} 


The following program reads from mailbox /dev/sd0 and prints the 
results to standard out: 
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main() 
{ 
int fd, cnt; 
char buf([4); 
fd = open("/dev/sd0", 2); 
cnt = read(fd, buf, 3); 
buf[cnt]=0; 
printf(buf); 
} 


sd LISTING 


The sd driver is separated into many files; however, these files are 
not separately compiled modules. The following is the code for 
the so driver. Each segment of the code is described in the 
previous sections. 


* sd.c -- Simple device driver. 

* this pseudo device driver implements a queue of characters 

* between two unrelated processes. The concept is similar to 
* a named pipe. There is a read side of the device and a write 
* side of the device. 


a 

finclude <sys/types.h> 
finclude <sys/param. h> 
finclude <sys/signal.h> 
finclude <sys/errno.h> 
finclude <sys/dir.h> 
finclude <sys/user.h> 
finclude <sys/sd.h> 
finclude <fcntl.h> 
#include <sd.h> 


[Bocnccc ence enn n eww ewe ween ecw ewe neem eww cme e ween enw eee e were en nc enn e eee 
* console messages defined if DEBUG is defined 

Foo 0 0 S088 00 6 06 60008 060 08 6808S FE O09 SOSSS SO SFSSSESCSOSATSEESHETHEESETEBSSEDE 
*/ 

#define DEBUG 

fifdef DEBUG /* if console debug messages are needed */ 


# define display(a,b) sddisp(a,b) 
# define print2(a,b) printf(a,b) 
felse 

# define display(a,b) 

# define print2(a,b) 
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fendif 
/* 6000 8 080 0 6 8 O60 O6 008 08 008008 208 6888089889 S9S88 SOS S88S8 S98 ES ESS SS2ON S208 ; 
* information defined during configuration 
eee ee et TT hy ee 
*/ 
extern struct sdinfo sd_sdinfo[]; /* information for each minor device */ 
extern int sd_cnt; /* number of minor devices */ 
/* mecc eee wee ce ecw cce ccc wseccwe we ew eccowscccewcecesseeercensesccecee 
* sd.h -- include file for sd driver 
Reo cccww eee wcrc wre wwe cwwecccecocceeocereesscesesecsscoseocesscesosscoss 
a 
/* woe ecece ec cece eecesornscoasenesecos eeeecce PTITTITTTiT ttt tt ttt ttt 
* information structure for each sd winor device 
We ccc wee wc cece come cece wwcweee cco soe sceoeeescnescousocace eecceccoacce 
a 
fdefine SDSIZE 3 /* wax number of characters in message */ 
struct sdinfo 
{ 
int state; /* state of the winor device */ 
int count; /* number of characters in message */ 


char buf([SOSIZE); /* characters in message */ 


[Becwenencccenoeen noc oreccnewccncecence ‘ChesnnEedSedsasesesscocsawaowa 
* possible values of state 

&  coccccccccceescoes eecasecccece evcvscasce ecceuceceseose stosaecoeen 
a 


#define SDMESSAGE 0x01 /* there is a message in buf */ 
#define SDRSLP 0x02 /* a process is asleep in sdread */ 
#define SDWSLP 0x04 /* a process is asleep in sdwrite */ 


i 
#define SDPRI PZERO + 5 /* sleep priority, signal interruptible */ 


et 
#define SDRSTATE 1 /* read the state variable for the minor device */ 
fdefine | SOWSTATE 2 /* write the state variable */ 


[teccccccecese re Locomwae ntittidm:tuciwavieacaveadbababeanadeiean 


* the read processes and the write processes need to sleep for an event. 
* this event is arbitrarily defined as an address in buf 
& i ccccceccccoe couse pew wre cece cence cones csowoseseseccosesrecseeconsocews 
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*/ 
fdefine  sdrsip(sdp) &sdp->buf[0] /* address for read process to sleep */ 


#define sdwslp(sdp) &sdp->buf[1] /* address for write process to sleep */ 
/ i ccdcaid enna annicenenkescegaesesatun wis Ree EOE REO 


* sdopen -- validate the minor device number. 


*] 
void sdopen(minor_d, flag) 
dev_t minor_d; /* minor device number */ 
int flag; /* flag indicating read/write */ 
{ 
if (minor_d >= sd_cnt) 
{ 
u.u_error = ENXIO; 
return; 
} 
} 
[Rocunnsanennenctendhdnedekeneedeccsconsceshusbowaecmseceensewcsebooss 
* sdclose -- not much 
© ccrccdedeCacsdnietebesnnds en Seneah eénadkdenkeneeesennaeneeesnceusee 
a; 
void sdelose(minor_d) 
dev_t minor_d; /* minor device number */ 
{ 
print2("sdclose\n"); 
} 
| thsacdokaradsiensanmeactenwsweis ace watlen 


* sdioct] -- perform the control functions 


Tr coce 966 SOS 0666 OS SESS SHES SS OEShEs SESEOS OBESE SEOEOScOeeESeSeeuCesse oo 
*/ 

void sdioctI(minor_d, cmd, arg) 

dev_t minor_d; 

int cmd; 

int * arg; 


{ 


struct sdinfo * sdp; 


sdp = &sd_sdinfo[minor_d]; 
switch (cmd) 


{ 

case(SDRSTATE): 
suword(arg, sdp->state); 
break; 

case(SDWSTATE): 
sdp->state = fuword(arg); 
break; 
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default: 
u.u_error = EINVAL; 
return; 

} 


* sdread -- read a message from the buffer. 

* sleep if there is no message in the buffer 

* transfer the message to user space 

* wakeup any write processes waiting for an empty buffer 


uf 
void sdread(minor_d) 
dev_t minor_d; 


{ 
struct sdinfo * sdp; /* pointer to minor device info structure */ 
char * strp; /* pointer to message in buf */ 


sdp = &sd_sdinfo[minor_d]; 
strp = sdp->buf; 


while (1(sdp->state & SDMESSAGE)) /* sleep if no message in buf */ 


{ 
sdp->state |= SORSLP; /* mark as sleeping */ 
sleep(sdrslp(sdp), SDPRI); /* sleep on address */ 
} 
while (sdp->count--) /* transfer message to user space */ 
if(passc(*strp++) == -1) 
break; 
sdp->state &= ~SDMESSAGE; /* there is no longer a message */ 
if (sdp->state & SDWSLP) /* if there are processes sleeping */ 
{ 
sdp->state &= ~SDWSLP; /* clear sleep state */ 
wakeup(sdws Ip(sdp)); /* wakeup all processes sleeping */ 
} 


* sdwrite -- write a message into the buffer. 

* sleep if there is a message in the buffer 

* transfer the message from user space 

* wakeup any read processes waiting for an empty buffer 


as | 
void sdwrite(minor_d) 
int minor_d; 


{ 
struct sdinfo * sdp; /* pointer to minor device info structure */ 
char * strp; /* pointer to message in buf */ 
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int 1; 
{nt c; 


sdp © &sd_sdinfo[minor_d]; 
strp = sdp->buf; 


while (sdp->state & SDMESSAGE) 
{ 
sdp->state |= SDWSLP; 
sleep(sdwsIp(sdp), SDPRI); 


} 


sdp->count = 0; 
for (i=SDSIZE; i--; sdp->count++) 
if((¢ = cpass()) = -1) 
break; 
else 
*strptt+ = c; 


sdp->state |= SDMESSAGE; 
if (sdp->state & SDRSLP) 


{ 
sdp->state &= “SDWSLP; 


wakeup(sdrslp(sdp)); 
} 
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/* counter */ 
/* character moved from user space */ 


/* sleep if message in buf */ 


/* mark as sleeping */ 
/* sleep on address */ 


/* transfer message from user space */ 


/* there is a message in the buffer */ 
/* if there are processes sleeping */ 


/* clear sleep state */ 
/* wakeup all processes sleeping */ 
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HARDWARE CONTROLLER REGISTERS 


Any controller or circuit board that meets Multibus specifications 
can be added to the system. A controller may have the 
intelligence to control many devices. For example, a terminal 
controller may control a number of terminals. The purpose of the 
device driver is to provide the interface for these boards. 


Controller functions are performed by writing and reading the 
values of addressable registers that reside on the controller. For 
example, writing a certain bit pattern to a control register on a 
terminal controller may change the baud rate of the controller. 
Writing a value to a data register on a terminal controller may 
cause the character 'a’ to be sent to a terminal. Reading the value 
of a data register may return a value corresponding to a keystroke. 
Also, a controller has the ability to interrupt the processor when it 
has completed a task. 


There is no general description of registers that can describe all 
controllers; each controller is unique. Figure 6.1 provides a basic 
block description of a typical controller. 


reads write interrupt 


control regs 


data regs 


device ports 
(1 or more) 


Multibus 
Controller 


Figure 6.1. Controller Block Description 
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READING AND WRITING DEVICE REGISTERS 


The PMC (Processor Memory Controller) contains the 
microprocessor chip and memory management unit. The 
microprocessor chip used in the 16-bit PMC is an MC68010. The 
32-bit PMC contains an MC68020 microprocessor. The PMC board 
executes process code and controls a device by reading and 
writing to registers located on the controller. 


Multibus specifies a special protocol to use when reading and 
writing device registers. This protocol is called Multibus 1/0. 
Kernel code (for example, the device driver) accesses device 
registers (Multibus |/O) when making reference to memory in the 
64K range of addresses: 


0x1f0000 - Ox fffff for 16-bit machines 
Oxff0000 - Oxffffff for 32-bit machines 


The actual address bits placed on the Multibus are the 16 least 
significant bits. The controllers respond to Multibus I/O addresses 
in the range: 


0x0000 - Oxffff 


Only the least significant 4 hex digits are actually placed on the 
Multibus WO lines. Typically, the addresses the controller 
responds to are adjustable by firmware strapping, or by software 
down loading. If, for example, a controller has two 2-byte registers 
that respond to the Multibus |\/O address of 0x0012 and 0x0014, 
the following C code writes the value 63 to one register: 


NOTE: The hex addresses shown in the examples apply to 
16-bit machines only. 


*(short *)(Ox1f0012) = 63; 


and this code reads the value of the other register and stores it in 
the variable val; 


short val; 
val = *(short *)(0x1f0014); 
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The standard method of handling the registers on a device is to 
define them as a structure. The following C declaration defines 
the device. 


struct device 
{ 
short data; /* data register */ 
shortcsr; /* contro] status register */ 
}; 
struct device *dev_addr = (struct device*)0x1f0012; 


To write to the data register, this C statement is executed: 
devy_addr->data = 63; 


To read from the control/status register, this C statement is 
executed: 


c = dev_addr->csr; 


BYTE ORDERING 


As shown in Figure 6.2, processors use one of two different 
schemes for byte ordering of 16-bit memory words. The 
MC68010/MC68020 family requires that 16-bit words reside on 
even byte boundaries and puts the most significant byte in the 
least significant address. Non-MC68010/MC68020 processors put 
the most significant byte in the most significant address. 


PMC Controller 
68000 non 68000 
low addr high addr low addr high addr 
[ msbyte |  Isbyte | {| Isbyte | msbyte | 
even byte addr odd byte addr even byte = odd byte 


Figure 6.2. Byte Ordering 
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It's important to understand exactly how the controller uses 
Multibus address and data lines when performing Multibus 
memory and Multibus \/O access. The following section describes 
how the PMC uses the address and data lines during Multibus 
access. 


During word transfers (16-bits) shown in Figure 6.3, the most 
significant byte in PMC local system memory corresponds to the 
most significant Multibus data bits (d8 - df). The least significant 
byte corresponds to the least significant Multibus data bits (dO - 
d7). Both the local system memory (LSM) address and the 
Multibus address must be even for word transfers. 


mov.w 10, 1f0000 PMC 
LSM addr LSM addr 
0010 0011 
even odd Multibus Multibus 
data lines address 

Dj 0 0000 
0} 7 
Dj 8 
o8 


Figure 6.3. Word Transfers 


During byte transfers (8-bits), the byte in PMC local system 
memory corresponds to the least significant Multibus data bits (d0 
- d7). The least significant bit of the address is always toggled. 
Figures 6.4 and 6.5 show the relationship of even and odd byte 
transfers. 


Bytes in PMC local system memory may have to be swapped 
before the controller accesses them. The least significant bit of 
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the address may need to be toggled before accessing byte 
addressable registers. 


mov.b 10,1f0000 PMC 


LSM addr LSM addr 
0010 0011 
even odd Multibus Multibus 
data lines address 
Oj] 0 0001 (Note the 
address change.) 
0} 7 
dD} 8 
ODO] f 


Figure 6.4. Even Byte Transfers 


mov.b 11,1f0001 PMC 


LSM addr LSM addr 

0010 0011 

even odd Multibus Multibus 
data lines address 
Di O 0000 (Note the 

address change.) 

Ge ey g 
Di; 8 
8 ae 


Figure 6.5. Odd Byte Transfers 
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MULTIBUS ADDRESS SPACE AVAILABLE TO 
CUSTOMERS 


The physical Multibus \/O addresses, 0x8000 - Ox9fff, are reserved 
exclusively for customer use. Only controllers that recognize 
addresses in this range can be added to the system. These board 
addresses correspond to the logical addresses of: 

© 0x1f0000 - Oxi fffff for 16-bit machines 

e Oxff0000 - Oxffffff for 32-bit machines 
Additionally, bus masters using the Common Bus Request 


(CBRQ/) signal must relinquish bus control within ten 
microseconds. 


BUS INTERRUPTS 


The bus permits two different types of interrupt devices to 
communicate with the PMC: 


e Bus vectored interrupt devices. 


e Auto vectored interrupt devices. 


BUS VECTORED INTERRUPTS 


When an external device generates an interrupt, it identifies itself 
to the PMC by passing a one byte vector to the MC68010 or 
MC68020. The vector is an index into a vector table (Figure 6.6). 


The contents of this table are the addresses of calls to a common 
dispatcher. The common dispatcher determines the vector 
number and indexes a table of interrupt service routines (ISRs) that 
handle the interrupts. This ISR table is called UNWvec and is 
created during configuration and stored in the univec.c file. 
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The bus vectored devices must be configured for a multibus 
interrupt level in the range of 0 to 6 (INTO/ to INT6/). 


interrupt Vector Table 


UNIvec 


Cspatcnr cats > Calls 


common dispatcher 


Figure 6.6. Interrupt Processing 
When the device generates an interrupt: 
e The current instruction finishes execution. 


e The value of the program counter and status register are 
pushed onto the stack. 


e The interrupt vector is translated into an address. 


« The address is loaded into the program counter (PC) and the 
status register (SR) is altered to represent the interrupt level, 
masking out all interrupts of equal or lower priority. 


Execution begins at the new address loaded in the PC, eventually 
resulting in the execution of a common dispatcher function which 
calls the ISR. All processing associated with the interrupt is 
executed by the interrupt service routine, called to service the 
interrupt. 


The return from the ISR causes the dispatch function to restore the 
old value of SR and PC and execution continues in the old 
process. 
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AUTOVECTORED INTERRUPTS 


Autovectored devices (devices that do not provide the one-byte 
vector address) must be configured for a multibus interrupt level of we 
7 (INT7/). When the INT7/ interrupt occurs, the microprocessor 
vectors to a memory location that contains the kernel’s ISR routine. 
The kernel's ISR sequentially accesses the ISR of each driver 
(through the poll table in univec.c) until the ISR of the device is 
reached that requested the interrupt. The ISR of the driver must 
be able to return a value of 1 to indicate to the kernel that it 
recognized the device interrupt. A return value of 0 indicates a 
device’s ISR has not recognized an interrupt. Should the ISR of 
the kernel reach the end of the poll table without a device ISR 
returning a value of 1, the kernel displays an error message of 
"spurious MB interrupt." 


ee ,,,,,,,,  EEoEEEEEEeEOEEE EEE ee V—VXKeV=_aa— — 


START OF DAY CONSIDERATIONS 


For kernel start of day routines, the kernel accesses each device 

drivers ISR to determine poll table configuration. If an wo 
autovectored device driver returns a value of 1, the address of the 

device ISR is left in the poll table. If a value of 0 is returned, the 

device ISR address is removed from the poll table. 


INTERRUPT VECTORS AVAILABLE TO CUSTOMERS 


A group of interrupt vectors for bus vectored devices are reserved 
exclusively for customer use. 


| Hex # | Decimal # { Hex Addr | 
| be-ce | 190-206 ! 2f8-338 | 


Figure 6.7. Customer Interrupt Vectors « » 


= —iia, 


Only controllers that can be strapped or programmed to generate 
these interrupt vectors can be integrated into the system. Multibus 
memory boards must respond to physical addresses in the range 
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of 0x200000 - Ox3fffff (2M). The task of mapping these boards into 
usable logical address space is described in Chapter 10. 


UP-12230 R1 6-9 


Chapter 7. 
High Performance Serial I/O Board 


OVERVIEW 


This chapter provides a hardware description of the High 
Performance Serial I/O (HPSIO) Controller. The purpose of this 
description is to present the type of hardware and software 
information that must be available to a device driver writer. 
Additionally, Appendix A provides a portion of the functional 
specification for the HPSIO. Chapter 8 includes an example 
device driver that controls the HPSIO. 


HPSIO FEATURES 
The HPSIO board (Figure 7.1) contains: 


e Four Dual Universal Asynchronous Receiver Transmitters 
(DUARTs) for the control of eight tty-type devices. 


e One parallel printer port. 
e An MC68010 processor. 


e 32K of on-board ROM containing programs that can be 
performed by request from the PMC. 


¢ 128K of on-board RAM that permits the downloading and 
executing of user programs. 
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dev 0 


dev 1 
DUART 
dev 2 DUART 
DUART 
dev 3 
DUART 


dev 4 
Parallel MC 
Printer Port 68010 


HPSIO Board 


dev 5 


dev 6 


Printer 


a 
@ 
< 
| 


Figure 7.1. HPSIO Board 


HPSIO INTERFACE 


The HPSIO board supports up to eight RS-232-C devices, such as 
terminals and line printers. The HPSIO controller also supports one 
parallel line printer. Communication between the HPSIO and the 
PMC is performed using 8 bytes of registers (Figure 7.2). The 8 
bytes of registers are mapped through the PMC memory 
management unit (MMU) to Multibus \/O space. The base 
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addresses of these registers are determined by the contents of a 
16-bit register on the HPSIO board. This 16-bit register has the 
> format shown in Figure 7.3. 


0 | 4 _| wailboxnegister 
[0 | 2 | Watibox Diagnostic Status 
[+ [2 [interrupt Vector Register 


Software Arbitration/Interrupt 
Status Register 


Figure 7.2. HPSIO Registers 


XXKEXKXKXKKXY FY ¥ OTD 


x Value determined by HPSIO board 
firmware (current value is 0x1400). 

y Value determined by three hardware 
straps. 

0 Value of bit is zero (0). 


Figure 7.3. HPSIO Address Register 


To communicate with the HPSIO board using Multibus \/O: 
on™ 1. Initialize the HPSIO interrupt vector register. 


2. Initialize an 1/O Parameter Block (IOPB) in memory. 
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For each HPSIO request (such as output), use an arbitration 
algorithm to access the HPSIO mailbox register. The lIOPB 
address must be written to the mailbox register, and the 
mailbox register must be released. 


lf a response is expected from the HPSIO, wait for the 
requested function to complete. 


lf Step 4 was required, decode the IOPB returned. 


NOTE: The hexadecimal logical addresses used in the 
example relate to the 16-bit machines only. 


16-bit logical address range = 0x1f0000 - Ox1fffff 
32-bit logical address range = Oxff0000 - Oxffffff 


The HPSIO register set is described using the following C 
code: 


struct chdev 


{ 

struct chlOPB *mailbox; 
unsigned short _ intrvector; 
unsigned short arb; 

} *hp = (struct chdev *) 0x1f1400; 


NOTE: The HPSIO board can access local system memory 
(LSM) directly to perform data transfer. 


MAILBOX REGISTER 


The mailbox register controls communication between the HPSIO 
board and the PMC board. The PMC requests a function to be 
performed by writing the address of an !/O Parameter Block (IOPB) 
into the mailbox register. An IOPB is a buffer in memory that 
describes the operation to be performed. All IOPBs have the same 
structure and are described in the IOPB section of this chapter. 
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The HPSIO performs the function described in an IOPB and then 
writes the IOPB address into the mailbox register. Each time the 
HPSIO writes to the mailbox register, the PMC is interrupted. Also, 
each time the PMC writes to the mailbox register, the HPSIO is 
interrupted. 


The following C code is performed to access the mailbox register 
for reading or writing: 


hp->mailbox = I0PBp; /* write address of IOPB to mailbox */ 


IOPBp = hp->mailbox; /* read address of IOPB from mai lbox*/ 


PMC HPSIO 


mailbox 
O 


iopb 


Figure 7.4. HPSIO/PMC Communication 


INTERRUPT VECTOR REGISTER 


The interrupt vector register must be initialized by the driver before 
an iobp is sent to the mailbox register. This is typically a start-of- 
day function. 


The interrupt vector register values define how bus vectored 


interrupts are generated and contains the parameters shown in 
Figure 7.5. 
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ra..a | Interrupt level (val values are 0 through 6) 
Tb | 0+ Enable interrupts; 1 = Disable interrupts 


Figure 7.5. Interrupt Vector Register 


The following C code initializes the interrupt vector register so that 
the HPSIO generates vector number 0x70 at interrupt level 2 each 
time the HPSIO writes to the mailbox register. 


hp->intrvector = 2<<8 + 0x70; 


INTERRUPT STATUS/ARBITRATION REGISTER 


The Interrupt Status/Arbitration Register contains 4-bits used to 

flag the existence of an interrupt, such as when the HPSIO has | 
written to the mailbox register. Also, there are flags used to ed 
implement an arbitration algorithm. 


Def inition 


If set, HPSIO has pending interrupt from PMC 


Be | write to mailbox register 
1 If set, PMC has pending interrupt from HPSIO 
write to mailbox register 


Zz ACK1 bit - if set, mailbox register in use 
REQ2 bit for arbitration 


Figure 7.6. Interrupt Status/Arbitration Register 


NOTE: The PMC must adhere to the arbitration algorithm. wy 
The arbitration algorithm is intended to prevent the PMC and 


HPSIO from using the mailbox register at the same time. The 
arbitration algorithm used by the PMC to access the mailbox 
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register is: 


e Turn on REQ2. 
e Delay for a few cycles. 


¢ Loop until ACK1 becomes 0. 
e Access the mailbox register. 


e Turn off REQ2. 


This algorithm can be performed using the following C code: 


hp->arbd = 0x80; 


/* turn on ACKI */ 


for (iedelay; 1; --1) /* delay a few cycles */ 


while (hp->arb & 0x40) /* loop until ACK] becomes 0 */ 


e 
’ 


hp->mailbox = IOPBp; /* access mailbox */ use the IOPB 
/* turn off REQ2 */ 


hp->arb &= 0x80; 


I/O PARAMETER BLOCK 


An I/O Parameter Block (IOPB) is defined by the following C 


structure: 


3 

struct chIOPB 
{ 
unsigned char 
unsigned char 
unsigned char 
unsigned char 
unsigned char 
unsigned char 
unsigned char 
unsigned char 
unsigned char 
unsigned char 


char* bufad; 
unsigned short 
}; 
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cstat; 
icntri; 
dstat; 
dchar; 


buflen: 


/* function code */ 
/* return status */ 
/* channel nusber */ 
/* trans. rate, signa) contro) */ 
/* parity type, char length */ 
/* # stop bits, oper. mode */ 
/* line status */ 
/* Interrupt Control/SRQ */ 
/* character status */ 
/* received character */ 

/* buffer start address */ 
/* buffer length */ 
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NOTE: 
One IOPB is dedicated to each HPSIO channel. | 


[OPB INTERFACE 


| 
The HPSIO firmware uses two types of data structures: LIOPB 
(load 1/O parameter block) and CIOPB (channel I/O parameter | 
block). Both the LIOPB and CIOPB are used to transmit 

commands to and receive commands from the system software. | 
Both structures are memory resident and can be accessed using a | 
pointer that is passed to the HPSIO firmware through the mailbox | 
register. 


The LIOPB is used for non-l/O specific functions, such as controller 
initialization, downloading, and return diagnostic log. Refer to | 
Appendix A for further information on the LIOPB structure. | 


The CIOPB is used for I/O specific functions, such as: 


e Channel Initialization | 
¢ Character Acknowledgement 

e Configure Interrupt 

e Output 

¢ Line Change Acknowledgement 


NOTE: The CIOPB is the IOPB referred to in the remaining 
sections of this book. 


Writing the IOPB address to the mailbox register causes an 
interrupt to the HPSIO board firmware. The firmware reads the | 
mailbox register contents, which clears the interrupt, and performs 
the function of the command contained in the IOPB. When the | 
function has been completed successfully, the firmware updates 
the IOPB and writes the IOPB address to the mailbox register, if 
required. This write generates an interrupt to the PMC board, if 

HPSIO interrupts are enabled. ww 


NOTE: The firmware does NOT overwrite the mailbox 
register contents. 
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Before any write is performed to the mailbox register, the firmware 
checks the Host Pending Interrupt bit in the Arbitration Register. If 
there is a pending interrupt, the firmware loops indefinitely until 
that interrupt is serviced. For example, until the the mailbox 
register is read. 


1/O COMPLETION - INCOMING IOPB’S 


All IOPB requests coming in to the HPSIO board generate an 
interrupt. There are three types of IOPB requests: 


e Type 1 requests are all HPSIO function requests that are 
returned with completion status information. All functions 
incoming to the HPSIO, except controller initialization and 
character acknowledge, are Type 1 functions. After the 
completion status information is placed in the IOPB for Type 
1 functions, the IOPB address is written to the mailbox 
register. 


Type 2 requests are any unsolicited service requests from 
the HPSIO to the PMC, such as line change. The IOPB used 
to initialize an HPSIO channel is also used for a Type 2 
function. Consequently, the HPSIO firmware requires that an 
[OPB, used for channel initialization, be maintained as an 
unsolicited IOPB until the next initialization function for that 
channel. REMEMBER: One IOPB is dedicated for each 
channel to handle all function requests for that channel. 


Refer to Appendix A for a list of all HPSIO functions. 


HPSIO COMMUNICATION CONCEPTS 


There are two types of communication between the PMC and the 
HPSIO boards: 


¢ Communication started by PMC 
« Communication started by HPSIO 
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The same data flow is performed for each type of communication: 


e A request is sent. 
e A response is returned. 


Function requests are always sent by the PMC. Operation 
complete, in the status code of the IOPB, is the HPSIO positive 
response to a function request. Service request, in the status 
code of the IOPB, is an unsolicited request from the HPSIO. When 
a terminal connected to the HPSIO sends a character, the HPSIO 
sends a service request to the PMC. 


PMC HPSIO 


function request 


operation compl. 


service request 


Started by PMC 


Started by HPSIO 


function request 


Figure 7.7. PMC/HPSIO Protocol 


CHANNEL INITIALIZATION 


Each channel on the HPSIO board must be initialized before any 
characters can be read from or written to that channel. Channel 
initialization is performed by the PMC by issuing an IOPB with the 
channel initialization function code. An IOPB address is written to 
the HPSIO mailbox register by the HPSIO firmware. Verification of 
the IOPB stat (status) field should reveal an “operation complete" 
status. 
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PMC HPSIO 


channel init. 


Started by PMC 


operation compl. 


Figure 7.8. Channel Initialization 


The following fields must be initialized in the IOPB before the 
channel initialization command can be performed. 


unsigned char func; /* function code */ 

unsigned char chan; /* channel number */ 

unsigned char cbhaud; /* transmission rate, signal control */ 
unsigned char cuodel; /* parity type, character length */ 
unsigned char cuode2; /* € stop bits, oper. mode */ 

unsigned char ientri; /* Interrupt Control/SRQ */ 


Here’s a brief description of each field: 
func Channel initialization (value 1). 


chan The channel number (0 through 7) for each serial port 
on the HPSIO. 


cbaud Baud rate, break on/off, input on/off, RTS on/off, DTR 
on/off. 


cmode? Character length and parity. 


cmode2_ Stop bit length, loopback, echo, non-echo operational 
mode. 


icntri Receiver interrupt enable, input line change interrupt 
enable. 
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During channel initialization, the PMC performs these functions: 
e Places the field values in the IOPB. 

¢ Arbitrates for the mailbox register. 

e Writes the IOPB address to the mailbox register. 

e Frees the mailbox register. 


e Waits for the HPSIO board to send a response. 
¢ Validates the stat (status) field of the HPSIO response. 


The HPSIO performs these functions: 
« Initializes the channel. 


¢ Changes the stat (status) field of the IOPB to show success; 
0 (operation complete) is the expected response. 


e Writes the address of the IOPB into the mailbox register. 


The |OPB used for channel initialization is also used for any 
unsolicited input requests. 


OUTPUT 

After a channel is initialized successfully, that channel can perform 
output. Typically, the PMC issues an IOPB with the output function 
code and expects the IOPB address to be written to the HPSIO 


mailbox register by the HPSIO firmware. Verification of the IOPB 
stat (status) field should reveal an “operation complete" status. 


PMC HPSIO 


output 


operation compl. 


Figure 7.9. Output Flow 


Started by PMC 


7-12 | UP-12230 R1 


High Performance Serial I/O Board 
BP Oe ER SS aS aE a SS TSN ES Ba ST OE sea 


The following fields must be initialized in an IOPB for output: 


unsigned char func; /* function code */ 
unsigned char chan; /* channel number */ 
char* bufad; /* buffer start address */ 
unsigned short buf len; /* buffer length */ 


Here is a brief description of each field: 
func Output (value 4). 


chan The channel number (0 through 7) for each serial port 
on the HPSIO. 


bufad Address of buffer to transmit. 


buflen Buffer length. 


NOTE: The protocol is the same as for channel initialization. 


INPUT 


After a channel is initialized successfully, that channel can perform 
input. 


PMC HPSIO 


Service request 


Data char. avail. 


Started by HPSIO 
Character Ack. 


Figure 7.10. Input Flow 
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The IOPB used during channel initialization is also used for all data 
character available service requests. The IOPB conditions include: 


¢ Service request (value 12) is found in the IOPB siat (status) field. 
e The Receiver Service Request bit in the icnt/ field should be on. 
¢ The character's status is found in the dstat field. 

° The character is found in the dchar field. 


The PMC must respond with a character acknowledgement 
command before another service request for the channel is mailed 
by the HPSIO. 


CHARACTER ACKNOWLEDGEMENT 


The character acknowledgement command informs the HPSIO 
firmware that the character has been read. If another character is 
available in the HPSIO buffer in RAM, the firmware places the next 
character, along with its status, in the IOPB and puts a service 
request value in the stat (status) field. 


After a character is received by the HPSIO from a terminal, the 
count of outstanding character acknowledgements is checked. If 
there are no acknowledgements outstanding, the IOPB is mailed to 
the PMC. If there is one or more outstanding acknowledgements, 
the new incoming character and its status is placed in the HPSIO’s 
buffer in RAM for later retrieval. 


When the last character acknowledgement IOPB is received (RAM 
‘buffer is empty), the count of outstanding acknowledgements is 
zero (0) and the IOPB is not returned. 


The service request IOPB can be mailed at any point in the input 
flow with an unexpected error status resulting from a memory 
parity error or a bus error. These errors conditions are reported in 
the stat field. 


The following fields must be initialized in an IOPB for a character 
acknowledgement. 
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unsigned char func; /* function code */ 
unsigned char chan; /* channel number */ 


Here is a brief description of each field: 
func Character acknowledgement (value 2). 


chan The channel number (0 through 7) for each serial port on 
the HPSIO. 
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A Character Device Driver 


OVERVIEW 


This chapter describes a device driver that controls the HPSIO 
board. Processes can read and write buffers of characters to tty 
devices attached to the HPSIO using this driver. Following a 
general overview, each driver routine is explained. 


DRIVER OVERVIEW 


Figure 8.1 shows the relationship between the various components 
of a character device driver. The dashed lines show control flow. 
Both function calls and wakeups control the execution of the driver 
code. The continuous lines show data flow to and from the 
controller. 
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Figure 8.1. Driver Block Description 
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Control Flow Example 


A process identifies the chread routine through the cdevsw table. 
The process executing chread may be put to sleep if more 
characters are requested than are currently available in the 
unsolicited input queue. The interrupt service routine, chintr, is 
invoked when a terminal user presses a key. When chintr has put 
enough characters into the unsolicited input queue to satisfy the 
process's request, it wakes up the process. 


Data Flow Example 


A process invokes the chwrite routine to send a buffer of 
information to a terminal. This buffer is copied to the output 
queue. Chstart takes characters off the output queue and sends 
them to the controller. 


Bottom End Output Logic 


The output portion of the bottom end of the driver is divided into 
two routines: the chsiart routine writes to the adapter’s registers to 
do the physical output; after the adapter generates an output 
complete interrupt, the ISR routine-chintr—calls the chstart routine 
to begin the next output. When the output queue becomes empty, 
the bottom end is temporarily finished with output and is 
considered to be not busy. When chwrite moves characters to the 
output queue and the bottom end is not busy, it must call chstart 
to start output. 
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Chopen Definition 


The open routine, chopen, is called using the cdevsw table. This 
routine is separated into four sections: 


1. Initial requirements 
2. Protect 
3. Channel initialization 


4. Unprotect 


Initial Requirements Section 


The initial requirements section permits or doesn’t permit the 
open. If all the requirements are satisfied, the open is permitted. 
lf all the requirements aren't met, the value of u.u_error is set and 
the routine stops. 


Protect Section 


The protect section protects the channel initialization section. The 
HPSIO can not have two channel initialization functions in progress 
at the same time. For example, if a channel initialization function is 
sent to channel 0 , a channel initialization function can not be sent 
to channel 1 until the channel initialization acknowledgement is 
received for channel 0. 
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lf the protect section detects a channel initialization in progress 
(indicated by the flag COPNPRG), it puts the process to sleep. Ifa 
process is put to sleep in the protect section, there must be a 
process executing code in the channel initialization section. As 
the process that is in the channel initialization section passes 
through the unprotect section, it issues a wakeup to processes put 
to sleep in the protect section. 


Channel Initialization Section 


The channel initialization section constructs a channel initialization 
lIOPB. The address of the IOPB is mailed to the HPSIO. The 
HPSIO initializes the channel and sends back a _ channel 
initialization acknowledgement. The process waiting for a channel 
initialization acknowledgment is put to sleep. The ISR routine, 
chintr, calls wakeup for the process when the channel initialization 
acknowledgement for this channel is received. 


Unprotect Section 


The unprotect section wakes up processes put to sleep in the 
protect section. When a process reaches this section, it has 
finished with the channel initialization and another channel can be 
initialized. All processes put to sleep in the protect section are 
issued a wakeup by processes passing through the unprotect 
section. 


CHOPEN LISTING 


chopen(minor_d, flag) 


dev_t minor_d; /* minor device */ 
int flag; /* open flag, bit 0 read, bit 1 write */ 
{ 
struct cinfo *cp; /* cinfo pointer for channel */ 
int priority; /* incomaing priority */ 
struct ciopb *fopb; /* jopb used locally */ 
printf(“open %x.", minor_d); 
[*eceecoercccce initial requirements --cccceewceeceeeeweewccncwerrccen= */ 
if (minor_d >= ch_cnt) /* validate the minor device number */ 
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u.u_error = EI0; 


switch (flag & 0x03) /* read/write flag */ 
{ 
case (0): /* no read / no write */ 
case (3): /* read / write */ 
u.u_error © EINVAL; 
break; 
case (1): /* read / no write */ 


if (cstate & COPENWRITE) 
u.u_error = EINVAL; 


else 
cstate |= COPENREAD; 
break; 
case (2): /* no read / write */ 


if (cstate & COPENREAD) 
u.u_error = EINVAL; 
else 
cstate |= COPENWRITE; 
break; 


} 


cp = &ch_cinfo[minor_d]; /* make sure it 1s not already open ia 
if (cp->state & COPEN) 
u.u_error = EBUSY; 


if (u.u_error) 
return; 


cp->state = COPEN; /* this channel is exclusively open */ 
[*eweeeeececen PPOLeCt -nnn nnn nnn nnn ewww nnn nnn nnn enn non encowenrenncnn */ 


priority = spl_c(); 
while(cstate & COPNPRG) 


{ /* while other open is in progress */ 
printf("sleeping in protect %x\n", minor_d); 
cstate |= COPNSLP; /* mark as sleeping */ 


sleep (&cstate, CPRI); 
printf(“wokeup in protect %x\n", minor_d); 


} 
cstate |= COPNPRG; /* mark open in progress */ 


[*ecceeeecvccee channel initialization -cccceenccnnecccceccecccrecceences al 
fopb = &ch_ciopb_io[minor_d]. input; 

fopb->func = init_fopb. func; 

{opb->chan * minor_d; 

fopb->cbaud = init_fopb.cbaud; 

jopb->cmodel = init_iopb.cmodel; 

jopb->cmode2 = init_lopb.cmode2; 

fopb->icntri = init_fopb. icntr; 


\ 
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cp->state {= CCIWAIT; /* mark as waiting for chan init ack */ 
carb(hp); /* write the command to the HPSIO mailbox */ 
emboxwrite(iopb, hp); 
emboxfree(hp); 
while(cp->state & CCIWAIT) /* waiting for the ISR to receive a */ 
{ /* channel init ack. */ 


cp->state |= CCISLP; /* mark as sleeping for a channel init ack */ 
sleep(cp, CPRI); 


UNPTOLECE ----nnnnnnnnnnnnnceccennecccncccnneccccces */ 
cstate &= ~COPNPRG; /* open is no longer in progress */ 
if (cstate & COPNSLP) /* some other processes are waiting to open */ 


{ 
cstate &= ~COPNSLP; /* now they can be awoke */ 


wakeup (&cstate); 


} 
spix(priority); 
printf("d"); 

} 


CHREAD DEFINITION 


The read routine, chread, is called using the cdoevsw table. 
Characters are taken off the unsolicited input queue and moved to 
a buffer in the program portion of the process. The clist, clin, 
represents the unsolicited input queue. If there aren’t enough 
characters in the unsolicited input queue, the process is put to 
sleep until enough characters are enqueued. 


The number of characters to transfer is in u.u_base when the 
process is executing chread. The u.u_base value is copied to the 
variable ccntin in chread. The ISR, chintr, enqueues characters as 
they are entered and wakes up the process sleeping in chread 
when clin has enough characters to satisfy the request. 
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The u.u_base value is copied to ccntin because a different u 
structure is active when the ISR is executing. 


CHREAD LISTING 


chread(minor_d) 
dev_t minor_d; 


* transfer characters from kernel] clist to user space. 
* the user must request the number of characters desired. 


* 4f not enough characters in the unsolicited input queue 
- sleep 
* move characters to user space 


*f 
{ 
struct cinfo * cp; /* info structure */ 
struct elist * cl; /* pointer to clist */ 
int priority; /* previous priority */ 


cp = &ch_cinfo[minor_d]; 


cl = &cp->clin; /* unsolicited input queue */ 
cp->ccntin = u.u_count; /* number of characters requested */ 
priority = spl_c(); /* critical section */ 
while (cp->ccntin > cl->c_cc) 
{ 
printf("chread: sleeping for input\n"); 
cp->state {= CINSLP; /* sleep until more chars are typed */ 
sleep(cl, CPRI); 
} 
splx(priority); 


while (passc(getc(cl)) != -1) /* pass to user space the characters */ 
: /* in the clist */ 


} 
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CHWRITE DEFINITION 


The write routine, chwrite, is called using the cdevsw table. 
Characters are copied from a program buffer into the output 
queue. The clist-clout-represents the output queue. A few 
characters are copied to the output queue, output is started if the 
minor device is not busy, and sleeps if the output queue reaches a 
high water mark. The steps are repeated until all of the buffer has 
been transferred to the output queue. The ISR issues a wakeup to 
a process sleeping in chwrite when the output queue goes below 
the low water mark. 


CHWRITE LISTING 


chwrite(minor_d) 
dev_t minor_d; 


* transfer characters from user space to kernel clist and start output. 
* while (characters to move) 
* move cfew characters clist 


* start output if not busy 
*  {f more characters to move 
* 1f number of characters in clist > CHIWATER 
. sleep 
Lf 
errr TTT TT TTTTtTtfttittttttttt TTT 
* 
{ 
struct cinfo * cp; /* info structure */ 
struct clist * cl; /* pointer to clist */ 
int priority; /* previous priority */ 
int c; /* character from user space */ 
{nt count; /* temp counter */ 


printf("wr %x\n", minor_d); 
cp = &ch_cinfo[minor_d]; 
cl = &cp->clout; 


c = cpass(); 


while (c l= -1) /* while characters to read */ 
{ /* move a few chars to clist */ 
for(count=cfew; (c != -1) && count; count-- ) 
{ /* chpute is not a kernel call */ 
chputc(c, cl); /* put the char in clist, maybe sleep */ 
c = cpass(); /* get the next char */ 
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} 


if(i(cp->state & CBUSY)) /* start output */ 
{ 
chstart(minor_d); 


} 


if (¢ t= -1) /* about to fall through */ 
priority = spl_c(); 
while (cl->c_cc > CHIWATER) /* wait for output to drain */ 
{ 
printf("ws %x.", minor_d); 
cp->state }= COSLP; 
sleep(cl, CPRI); 
printf ("ww %x.", minor_d); 


} 
sp)x(priority); 
} 
} 
CHCLOSE DEFINITION 


The close routine, chclose, is called using the cdevsw table. The 
process executing chclose must be suspended until all characters 
in the output queue have been given to the controller. The output 
queue is empty if it has zero characters. The ISR issues a wakeup 
to processes sleeping in chclose when the output queue is empty. 


CHCLOSE LISTING 


chclose(minor_d) 


{ 

struct cinfo “cp; /* pointer to cinfo structure */ 
struct clist * cl; /* pointer to clist */ 

int priority; /* processor priority level */ 


cp = &ch_cinfo[minor_d); 
cl = &cp->clout; 


priority = spl_c(); 

while (cl->c_cc > 0) /* wait for output to drain completely */ 
{ 
cp->state j= CCLSSLP; 
sleep(cl, CPRI); 
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} 
cp->state = 0; /* reset for the next process to open */ 
spix(priority); 
} 
CHINIT DEFINITION 


The initialization routine, chint, is executed once during boot up 
initialization. The interrupt vector register on the HPSIO is 
initialized. 


CHINIT.C LISTING 


a! 

extern int ch_cnt; /* number of channels */ 

extern struct cinfo ch_cinfo[); /* information structure */ 

extern struct clopb_io ch_ciopb_io[]; /* input/output fopb array */ 


struct cdev *hp = CREGBASE; 


/* channel initialization command */ 

struct ciopb init_fopb = 

/* func stat chan cbaud cmodel cmode2 cstat icntr] dstat dchar bufad buflen */ 
{CFCHANINIT,O,0, Oxeb, Ox02, 0x07, 0, Ox0l, 0, 0, 0, OQ}; 


int cfew = CFEW; /* number of characters to write at a time */ 
int cstate = 0; /* state of device as a whole see COPNSLP */ 


chinit() 
* {initialization routine. 


* the interrupt vector register needs to be initialized with 
* the interrupt vector, priority level (0..7), and enable interrupts 


hp->intrvector = CINTLEVEL<<8 | CVECTOR; 
printf("c started interrupt vector %x\n", hp->intrvector); 


} 
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CHSTART DEFINITION 


The start routine, chstart, is the output portion of the bottom end of 
the driver. A cblock is taken off the output cl/ist and an output 
lIOPB is constructed using the cblock. It is important that this 
cblock be returned to the freelist. An interrupt is generated when 
the HPSIO has completed the output operation, so the ISR must 
perform clean up functions. It is important to understand the 
reason for the start routine. At first glance, it may seem that the 
start function should be contained within the ISR. Each time an 
output request is completed, it's time to begin another output. A 
problem arises when the device is idle. The write routine needs a 
method to “start” the output after adding to an empty queue. In 
short, the start routine is the code necessary to start an output 
operation; it is called by the ISR and the write routine. 


CHSTART LISTING 


chstart(minor_d) _ 
dev_t minor_d; 


* start jo on one of the channels, 

* the channel is not busy - guaranteed 

* if there is a block on clist 

* write output fopd for list 

* mark state as busy 

* 

* note that the block taken off list is put in a the variable: cblock 
* so that the ISR may return it to the free list 


i 
struct clist * cl; /* clist */ 
struct cinfo * cp; /* ¢ information */ 
struct ciopb * fopb; /* fopd filled for output */ 
struct cblock * bp; /* temporary cblock pointer */ 


cp © &ch_cinfo[minor_d); 
cl = &cp->clout; 
fopb = &ch_ciopb_io[minor_d].output; 
/* if there are no more cblocks */ 
if ((bp = cp->cbout = getcb(cl)) == 0) 
panic("chstart called with nothing to print\n"); 
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fopb->func = CFOUTPUT; /* make jopb */ 
fopb->chan = minor_d; 

fopb->bufad = &bp->c_data[bp->c_first]; 
fopb->buflen = bp->c_last - bp->c_first; 


cp->state j= CBUSY; /* mark as busy */ 


carb(hp); /* write to mailbox register */ 
cmboxwrite(fopb, hp); 
cmboxfree(hp); 
} 
CHINTR DEFINITION 


Chintr is the ISR that handles all interrupts. There are three types 
of IOPB’s that can be made by the HPSIO and delivered to the 
mailbox: 


e Channel initialization acknowledgement 
e Character typed 
e Output acknowledgement 


There is an input and output IOPB for each channel. The input 
lOPB is first used for channel initialization and channel initialization 
exchange. After initialization, the input IOPB is used for the 
service request (for example, a character entered from the 
terminal) and character acknowledge exchange. 


The output IOPB is used for the output request and output 
acknowledge exchange. 


Channel Initialization Acknowledgement (CFCHANINIT) 


When the channel initialization is completed, the HPSIO sends 
back a channel initialization acknowledgement. An interrupt is 
generated, chinir examines the IOPB returned, and it is verified. If 
a process is asleep in the chopen routine waiting for a channel 
initialization acknowledgement, the process is issued a wakeup. 
The function code is set to CFCHARACK because all remaining 
functions for this IOPB are for character acknowledgements. 
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Character Typed (CFCHARACK) 


A character entered at the keyboard causes the HPSIO to send a 
service request. A service request is unsolicited input and, 
therefore, needs to be added to the unsolicited input queue. The 
lIOPB is verified. If a process is asleep in the chread routine, it is 
issued a wakeup if enough characters are on the unsolicited input 
queue. 


Output Acknowledgement (CFOUTPUT) 


After the HPSIO has completed processing an output request, an 
output acknowledgement IOPB is delivered to the PMC. The 
cblock used for the output must be put back on the free list. 


lf a process is asleep in the driver's chwrite routine waiting for the 
output clist to become empty, the process is issued a wakeup 
when the queue is below the low water mark. If a process is put to 
sleep in the driver's chclose routine waiting for the output clist to 
become emply, the process is issued a wakeup when the queue 
becomes empty. 
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lf there are more characters in the output clist, the chstart routine 


must be called to start the output of another cblock. 
CHINTR LISTING 


chintr() 

[Povevcvecoccsonessevecceccscecucsccesscsccccss AdksUeRKS SNE RNEReRRKen ene 
* ISR 

* arbitrate for the mailbox 

* read the mailbox register 

* case(Acknowledged Channel Init CIOPB) 

* validate the jopb 


* case(Acknowledged output) 

* validate the jopb 

* return the cblock that was printed back to the free list 
* wakeup upper half if needed 

* call start to start the next cblock 

sd 
* 
& 


free the mailbox 


ad | 
{ 
struct ciopb * fopb; /* 4opb in the mailbox */ 
struct cinfo * cp; /* info structure that caused int */ 
struct clist * cl; /* clist pointer */ 
int minor_d; /* minor device number */ 
char tmp_func; /* temporary function holder */ 
int priority; /* priority level */ 
carb(hp); /* ask for use of the mailbox */ 
cmboxread(fopb, hp); /* read the mailbox */ 


/* jopb numer ({e channel number) */ 


minor_d = ({opb - (struct clopb *)ch_ciopb_{o)/2; 
cp = &ch_cinfo[minor_d]; /* info structure pointer */ 
printf("i%x", minor_d); 


switch (fopb->func) 


{ 
/* eda sa cdotacdaada cde tedec cee ceeSeseedddoeadseceupacuvvececenecaaseeoto */ 
case (CFCHANINIT): /* Acknowledged Channel Init CIOPB */ 
/*printf("c1");*/ 
if (jopb->stat != CSOPCPL) 
{ 


break; 
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} 
/*-- channel initialization wakeup --*/ 
cp->state &= ~CCIWAIT; /* no longer waiting for chan init ack */ 
 if(cp->state & CCISLP) /* if sleeping for a chan init ack */ 
{ wa 
cp->state &= ~CCISLP; /* no longer sleeping for chan init ack */ 
wakeup(cp); /* wakeup processes waiting for */ 
} /* chan init ack */ 
fopb->func = CFCHARACK; /* from now on it will be input */ 
break; | 
/* oe wee cece ww wee ecw www ewww www cece wwe wwe ew eww cco wooo cw cccccccece */ 
case (CFCHARACK): /* character has been typed */ 
if(!(fopb->{icntr] & CRCVSR)) 
pr_iopb(fopb, "char ack but no CRCVSR"); 
printf("in char"); 
cl = &cp->clin; /* unsolicited input queue */ 
putc({opb->dchar, cl); /* store the character away */ 
cuboxfree(hp); 
carb(hp); /* ask for use of the mailbox */ 
priority = spl0(); 
sp1x(priority); 
cmboxwrite(iopb, hp); /* write a char ack to the hpsio */ wy 
/*-- input wakeup --*/ 
if (cp->state & CINSLP) /* process sleeping on input */ 
if (cl->c_cc >= cp->ccntin) /* worth waking up */ 
{ 
cp->state &= ~CINSLP; 
wakeup(cl); 
} 
break; 
/* mmewe cece wee wcccce cc wwescwccoessweseweccooccosccocessoscoescoe */ 
case (CFOUTPUT): /* acknowledged output */ 
printf("o%x", minor_d); 
if (iopb->stat != CSOPCPL) 
{ 
clogerr({4opb, “output failed: operation not complete"); 
break; 
} 

/*-- output wakeup --*/ 
putcf(cp->cbout); /* return the cblock to free list */ 
if (cp->clout.c_cc <= CLOWATER) /* wake up top half if drained */ ww 

if(cp->state & COSLP) /* and if sleeping for output */ 
{ 
cp->state &= ~COSLP; 
wakeup(&cp->c lout); 
} 
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/*-- close wakeup --*/ 


if (cp->clout.c_cc == 0) /* wake close if drained to zero */ 
{ 
cp->state &= ~CBUSY; /* no longer busy */ 
if(cp->state & CCLSSLP) /* and if sleeping for close */ 
{ 


Cp->state &= “CCLSSLP; 
wakeup(&cp->c lout); 


} 


else 
chstart(minor_d); /* start up the next transaction */ 
break; 
default: 
clogerr(fopb, "unexpected interrupt”); 
break; 
} /* end switch */ 
cuboxfree(hp); 
printf("e"); 
} 


MASTER/DFILE ENTRIES 


The following lines in the master file describe the ch driver. 


“a{2{ 3{4{5 [6] mb} ac }o}io} m | iz 
eh | 4} us7] 4 {ch} ajo | at | 8] 4 | cinfo | ciopb_io | 


This line in the dfile for the config program describes the ch driver: 


ee 761206 
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CREATING/TESTING THE KERNEL 
The following commands create the device nodes: 


# /etc/mknod /dev/chO c 21 cO 
# /etc/mknod /dev/ch1 c 21 c1 
# /etc/mknod /dev/ch2 c 21 c2 
# /etc/mknod /dev/ch3 c 21 c3 
# /etc/mknod /dev/ch4 c 21 c4 
# /etc/mknod /dev/ch5 c 21 c5 
# /etc/mknod /dev/ch6 c 21 c6 
# /etc/mknod /dev/ch7 c 21 c7 


This makefile creates the kernel: 


test = ch.o 


é define for name.o so boot up console messages are printed out correctly 
SYS = UTS V 


VER = yours 
NODE = 5000 
REL = 1R1 


# MACH = 68010 for 5000/20 and 5000/40 
# MACH = 68020 for 5000/30, 5000/35, 5000/50, 5000/55, and 32-bit 5000/40 
MACH = 68010 
DEFS = —--DSYS="\"$(SYS)\"" \ 
-DVER="\"$(VER)\"" \ 
-DNODE="\\"$(NODE)\"" \ 
-DREL="\"$(REL)\"" \ 


-DMACH="\"$(MACH)\"" 
AS s as 
cc = cc 


# RELOC = 108000 for 5000/20 and 5000/40 

f RELOC = £00000 for 5000/30, 5000/35, 5000/50, 5000/55, and 32-bit 5000/40 
RELOC = 108000** 

CFLAGS = -K <I. -I$(INCRT) 

LFLAGS 2 eR $(RELOC) -N -e susentry 


LIBS =  $/kernel/sperry 

INCRT = /usr/ include 

MASTER ® /usr/acct/yours/master 
.c.0 $(CC) $(CFLAGS) -c $< 


.$.0 $(AS) $(ASFLAG) -o $*.0 $*.s 
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tape: unix 
bootmedia t unix 

| flex: unix 
bootmedia f unix 


unix: conf.o name.o univec.o $(LIBS)/1ib[0-9] $(test) 
1d $(LFLAGS) /kernel/sperry/ml/start.o\ 
$(test)\ 
‘ , 
univec.o\ 
conf.o\ 
name.o\ 
/usr/acct/yours/1linesw.o\ 
$(LIBS)/14b[0-9)\ 
$(LIBS)/11b3\ 
-o unix\ 
2> undefs 


name.o: $(INCRT)/sys/utsname.h 
$(CC) $(CFLAGS) $(DEFS) -c name.c 


las conf.o: conf.c 
univec.o: univec.c 


conf.c:  config.cf $(MASTER) 
config -m $(MASTER) config.cf 
fixconf 


ch.o: ch.h\ 

ch.c\ 

chclose.c\ 
chinit.c\ 
chintr.c\ 
chiocti.c\ 
chopen.c\ 
chread.c\ 
chrest.c\ 
chstart.c\ 
chwrite.c 
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This program displays a file on terminal 2: 


$ cp /etc/termcap /dev/ch2 


COMPLETE SOURCE LISTING 


/* 
* ch.c -- A character device driver 
*/ 


finclude “sys/paras.h° 
finclude “sys/types.h" 
finclude "sys/dir.h® 
finclude “sys/signal.h® 
finclude *sys/user.h" 
finclude “sys/errno.h” 
finclude “sys/tty.h” 


finclude "ch.h® 


finclude “chinit.c* 
finclude “chopen.c" 
#include “chwrite.c* 
finclude “chread.c” 
finclude “chstart.c" 
finclude “chintr.c* 
finclude “chclose.c” 
finclude “chioct].c* 
#include “chrest.c” 


*/ 

extern int ch_cnt; /* number of channels */ 

extern struct cinfo ch_cinfo[]; /* information structure */ 

extern struct ciopb_{o ch_ciopb_{o[]; /* input/output fopb array */ 


struct cdev *hp = CREGBASE; 

/* channel initialization command */ 

struct ciopb init_iopd = 

/* fune stat chan cbaud cmodel cmode2 cstat icntr] dstat dchar bufad buflen */ 
{CFCHANINIT,0,0, Oxeb, 0x02, Ox07, 0, Ox0l, 0, OO, 0, O}; 


int cfew = CFEW;/* number of characters to write at a time */ 
int cstate = 0; /* state of device as a whole see COPNSLP */ 
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chinit() 


* {initialization routine. 
* the interrupt vector register needs to be initialized with 
* the interrupt vector, priority level (0..7), and enable interrupts 


a 
{ 
hp->intrvector = CINTLEVEL<<8 {| CVECTOR; 
printf("c started interrupt vector %x\n", hp->intrvector); 
} 
chopen(minor_d, flag) 
dev_t minor_d; /* minor device */ 
int flag; /* open flag, bit 0 read, bit 1 write */ 
{ 
struct cinfo *cp; /* cinfo pointer for channel */ 
int priority; /* incomming priority */ 
struct clopb *fopb; /* jopb used locally */ 


printf(“open %x.", minor_d); 


[*eeeee coerce initial requirementS ----------ecnn nnn nnn nw enw nen nnnne i 
if (minor_d >= ch_cnt) /* validate the minor device number */ 
u.u_error = E10; 
switch (flag & 0x03) /* read/write flag */ 
{ 
case (0): /* no read / no write */ 
case (3): /* read / write */ 
u.u_error = EINVAL; 
break; 
case (1): /* read / no write */ 


if (cstate & COPENWRITE) 
u.u_error = EINVAL; 


else 
cstate }= COPENREAD; 
break; 
case (2): /* no read / write */ 


if (cstate & COPENREAD) 
u.u_error = EINVAL; 
else 
cstate j= COPENWRITE; 
break; 


} 
cp = &ch_cinfo[minor_d}; /* make sure it is not already open */ 
if (cp->state & COPEN) 


u.u_error = EBUSY; 


if (u.u_error) 
return; 
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cp->state = COPEN; /* this channel is exclusively open */ 


[*eneeeen econo PPOLECt -- nnn enn nnn n nn nen nn nn nnn nme n mene wenn n ncn eeeeee */ 
priority = spl_c(); 
while(cstate & COPNPRG) 


{ /* while other open is in progress */ 
printf("sleeping in protect %x\n", minor_d); 
cstate |= COPNSLP; /* mark as sleeping */ 


sleep (&cstate, CPRI); 
printf("wokeup in protect %x\n", minor_d); 


} 
cstate {= COPNPRG; /* mark open in progress */ 


[*ecceeeecrecces Channel initialization -------cecnnn enw eww ew wweeececee */ 
fopb = &ch_ciopb_io[minor_d). input; 

iopb->func = init_iopb. func; 

jopb->chan = minor_d; 

fopb->cbaud = init_{opb.cbaud; 

fopb->cmodel = init_fopb.cmodel; 

jopb->cmode2 = init_iopb.cmode2; 

fopb->icntrl © init_fopb. fentrl; 


cp->state j= CCIWAIT; /* mark as waiting for chan init ack */ 
carb(hp); /* write the command to the HPSIO mailbox */ 
cmboxwrite({fopb, hp); 
cmboxfree(hp); 
while(cp->state & CCIWAIT ) /* waiting for the ISR to receive a */ 
{ /* channel init ack. */ 


cp->state j= CCISLP; /* mark as sleeping for a channel init ack */ 
sleep(cp, CPRI); 


[*eeeecccereee- UNPTOLECE ono nnn ene w nn enn nnn nnn en wn ne ecewweenocence */ 
cstate &= ~COPNPRG; /* open is no longer in progress */ 
if (cstate & COPNSLP) /* some other processes are waiting to open */ 
{ 
cstate &= ~COPNSLP; /* now they can be awoke */ 
wakeup (&cstate); 
} 
sp1x(priority); 
printf("d"); 


chwrite(minor_d) 
dev_t minor_d; 


* transfer characters from user space to kernel clist and start output. 
* while (characters to move) 

* move cfew characters clist 

* start output if not busy 

* f more characters to move 
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* if number of characters in clist > CHIWATER 
. sleep 
t 
OK cc eed SeSe ewes deed de wees eSo db SS OS SSeS b SSS TORS SSE KSEE SKEHHES TSE ODO CECS 
sf j 
{ 
struct cinfo * cp; /* info structure */ 
struct clist * cl; /* pointer to clist */ 
int priority; /* previous priority */ 
int ¢; /* character from user space */ 
int count; /* temp counter */ 


printf("wr %x\n", minor_d); 
cp = &ch_cinfo[minor_d]; 
cl = &cp->clout; 


c = cpass(); 

while (c l= -1) /* while characters to read */ 
{ /* wove a few chars to clist */ 
for(count=cfew; (c l= -1) && count; count-- ) 


{ 
chputc(c, ¢1); 
c = cpass(); 


/* chputc is not a kernel call */ 
/* put the char in clist, maybe sleep */ 
/* get the next char */ 


} 


if(i(cp->state & CBUSY)) /* start output */ 
{ 


chstart(minor_d); 


} 


if (c le -1) /* about to fall through */ 
priority = spl_c(); 
while (cl->c_cc > CHIWATER) /* wait for output to drain */ 
{ 
printf("ws %x.", minor_d); 
cp->state |= COSLP; 
sleep(cl, CPRI); 
printf ("ww %x.", minor_d); 
} 
spix(priority); 
; 
} 


chread(minor_d) 
dev_t minor_d; 


transfer characters from kernel clist to user space. 
the user must request the number of characters desired. 


if not enough characters in the unsolicited input queue 


* 
* 
& 
* 
. sleep 
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* move characters to user space 


*} 
{ 
struct cinfo * cp; /* info structure */ 
struct clist * cl; /* pointer to clist */ 
int priority; /* previous priority */ 


cp © &ch_cinfo[minor_d); 


cl = &cp->clin; /* unsolicited input queue */ 
cp->ccntin = u.u_count; /* number of characters requested */ 
priority = spl_c(); /* critical section */ 
while (cp->ccntin > cl->c_cc) 
{ 
printf("chread: sleeping for input\n"); 
cp->state j= CINSLP; /* sleep until more chars are typed */ 
sleep(cl, CPRI); 
} 
spix(priority); 


while (passc(getc(cl)) l= -1) /* pass to user space the characters */ 
: /* in the clist */ 


chstart(minor_d) 
dev_t minor_d; 


* start io on one of the channels, 

* the channel is not busy - guaranteed 
* 4f there is a block on clist 

* write output jopb for list 

* mark state as busy 


* note that the block taken off list is put in a the variable: cblock 
* so that the ISR may return it to the free list 


a 
{ 
struct clist * cl; {* clist */ 
struct cinfo * cp; /* c information */ 
struct ciopb * iopb; /* jopb filled for output */ 
struct cblock * bp; /* temporary cblock pointer */ 


cp = &ch_cinfo[minor_d]; 
cl = &cp->clout; 
{opb = &ch_cfopb_io[minor_d]. output; 
/* if there are no more cblocks */ 
if ((bp = cp->cbout = getcb(cl)) == 0) 
panic(*chstart called with nothing to print\n"); 
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fopb->func = CFOUTPUT; /* make fopb */ 
fopb->chan = minor_d; 

lopb->bufad = &bp->c_data[bp->c_first]; 
lopb->buflen = bp->c_last - bp->c_first; 


cp->state {= CBUSY; /* mark as busy */ 


carb(hp); /* write to mailbox register */ 
cmboxwrite(fopb, hp); 
cmboxfree(hp); 
} 
chintr() 
Jl ccackesabneksiqneneeewesenbeesieenesbusiebesdseccceuswedeeitedenacenecas 
* ISR 


* arbitrate for the ma i 1box 
* read the mailbox register 
* case(Acknowledged Channel Init CIOPB) 


* 


* £¢* ¢ © © © &© & #® 


validate the iopb 


case(Acknowledged output) 


validate the fopb 


return the cblock that was printed back to the free list 


wakeup upper half if needed 
call start to start the next cblock 


free the mailbox 


{ 

struct ciopb * fopb; /* fopb in the mailbox */ 

struct cinfo * cp; /* info structure that caused int */ 
struct clist * cl; /* clist pointer */ 

int minor_d; /* minor device number */ 

char tmp_func; /* temporary function holder */ 

int priority; /* priority level */ 

card(hp); /* ask for use of the mailbox */ 
cmboxread({opb, hp); /* read the mailbox */ 


/* fopb numer (ie channel number) */ 
minor_d = (fopb - (struct ciopb *)ch_ciopb_1o)/2; 
cp = &ch_cinfo[minor_d]; /* info structure pointer */ 
printf("i%x", minor_d); 


switch (fopb->func) 


{ 
/* Cece rece cee ce ceeweceee ce secesccewssewenseeeceseccecocccnecesusoasse */ 
case (CFCHANINIT): /* Acknowledged Channel Init CIOPB */ 


/*printf("ci")3*/ 
if (jopb->stat |= CSOPCPL) 


UP-12230 R1 8-25 


Chapter 8 


EL a 


{ 

clogerr(iopb, “channel init failed: operation not complete"); 
break; 

} 

/*-- channel initialization wakeup --*/ 
cp->state &= ~CCIWAIT; /* no longer waiting for chan init ack */ 
if(cp->state & CCISLP) /* if sleeping for a chan init ack */ 

{ 
cp->state &= ~CCISLP; /* no longer sleeping for chan init ack */ 
wakeup(cp); _ /* wakeup processes waiting for *] 
} /* chan init ack */ 
fopb->func = CFCHARACK; /* from now on it will be input */ 
break; . 
/* eee meee eww wwe c eww wc ccm ewe cece wc ccc cee ccc cw ce ewoecc ccc occ cccoccecce w/ 
case (CFCHARACK): /* character has been typed */ 


{f(1(4opb->icntr1 & CRCVSR)) 
pr_fopb(fopb, “char ack but no CRCVSR"); 
printf("in char"); 


cl = &cp->clin; /* unsolicited input queue */ 
putc(fopb->dchar, cl); /* store the character away */ 
cmboxfree(hp); 
carb(hp); /* ask for use of the mailbox */ 
priority = spl0(); 
sp1x(priority); 
cmboxwrite(iopb, hp); /* write a char ack to the hpsio */ 
/*-- input wakeup --*/ 
if (cp->state & CINSLP) /* process sleeping on input */ 
if (cl->c_cc >= cp->ccntin) /* worth waking up */ 
{ 
cp->state &= ~CINSLP; 
wakeup(cl); 
} 
break; 
/* weeewecwewcencecccweccewecccecccoecesoscocose secccoceecoceoscccooce e/ 
case (CFOUTPUT): /* acknowledged output */ 


printf("o%x", winor_d); 
if (iopb->stat |= CSOPCPL) 


{ 

clogerr({opb, “output failed: operation not complete"); 
break; 

} 

/*-- output wakeup --*/ 
putcf(cp->cbout); /* return the cblock to free list */ 
if (cp->clout.c_cc <= CLOWATER) /* wake up top half if drained */ 

if(cp->state & COSLP) /* and if sleeping for output */ 


{ 
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cp->state &= ~COSLP; 


wakeup(&cp->c lout); 


} 
/*-- close wakeup --*/ 
if (cp->clout.c_ce == 0) /* wake close if drained to zero */ 
{ 
Cp->state &= ~CBUSY; /* no longer busy */ 
if(cp->state & CCLSSLP) /* and if sleeping for close */ 
{ 
Cp->state &= ~CCLSSLP; 
wakeup(&cp->c lout); 
} 
} 
else 
chstart(minor_d); /* start up the next transaction */ 
break; 
default: 


clogerr(fopb, “unexpected interrupt”); 


break; 
} /* end switch */ 


cmboxfree(hp); 
printf("e"); 
} 
chclose(minor_d) 
{ 
struct cinfo *cp; 
struct clist * cl; 
int priority; 


cp © &ch_cinfo[minor_d); 
c} PD] &cp->c lout; 


priority = spl_c(); 

while (cl->c_cc > 0) 
{ 
cp->state |= CCLSSLP; 
sleep(cl, CPRI); 
} 

cp->state = 0; 

sp)x(priority); 

} 

chioct1() 
{ 
printf("chioct1:\n"); 
} 

chputc(c, cl) 

char c; 

struct clist *cl; 
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/* pointer to clist */ 
/* processor priority level */ 


/* wait for output to drain completely */ 


/* reset for the next process to open */ 


8-27 


Chapter 8 


* put a character onto the clist cl. 
* transforgations of single character into multiple chars is also 


* performed 
*f 
{ 
switch(c) 
{ 


case('\n'): 


chputc('\r', cl); 


default: 


while(putc(c, cl) == -1) 


{ 


} 
} 
} 
es 
carb(hp) 
struct cdev * hp; 
{ 
int 1; 


hp->arb j= CO_REQ2; 


for (120; 1<256; ++1) 


while (hp->arb & CO_ACK1) 


} 


clogerr({opb, str) 
char *str; 
struct ciopb * fopb; 


pr_iopb(fopb, str); 
} 


pr_iopb(p, str) 
char *str; 


‘ 
\ 
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/* hpsio device address */ 


/* activate the REQ2 bit */ 


/* wait for board to finish */ 


/* sleep until freelist has blocks */ 
printf("cwrite: sleep for cfreelist\n"); 

cfreelist.c_flag = 1; 

sleep(&cfreelist, CPRI); 
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struct ciopb * p; 


a 
{ 
int 1; 
printf(str); 
printf("\n fopb: "); 
printf("func %x, stat %x, chan %x, cbuad %x, cmodel x, \ 
cmode2 %x\n", p->func, p->stat, p->chan, p->cbaud, \ 
p->cmodel, p->cmode2); 
printf("cstat x, icntr] %x, dstat %x, dchar %x, \ 
bufad %x, buflen %x\n", p->cstat, p->icntrl, p->dstat, \ 
p->dchar, p->bufad, p->buflen); 
} 
JR cna caaiadanesieawadee dines edabadd anes ecasniamaeuboanteeeseeoulse 
* character device information information for each channel 
SCC SSeoee SH SSS NS EOSRSRESESOSESESEEEES CO SSEHSTSE Sw SERED SSSESSeESeSESCEEOS 
"y 
struct cinfo 
{ 
short state; /* state of channel */ 
struct cblock *cbout; /* cblock being printed */ 
struct clist clout; /* clist used as output queue*/ 
struct clist clin; /* clist used as unsolicited input queue */ 
int ccntin; /* number of chars needed in input clist */ 
[Sine inna Genuididie shee deiee iueuen saeene ne eeeRiaseecacelaukesmewad 
* macros for writing, reading, and freeing the mailbox register 
S.C RSSSRR SSO SENDS KSS SEKRESE HERS RSSNSESHHOSEESESETECSE DESO DOSEEEESCSOESEHESR EDS 
af 
#define cmboxwrite(fopb, c) c->mailbox = fopb /* write to mailbox */ 
#define cmboxread(iopb, c) fopb = c->mailbox /* read mailbox */ 
#define cmboxfree(hp) hp->arb &= ~CO_REQ2; /* free the mailbox */ 
[Bocccecccncceccccenecncenccccnnewnwnecensececcewenncncenesescesecceeesese 
* state bits for controller as a whole as kept in: state 
5 eT TTT TrTTrrTrrrrrrrireirrrriittttt ttt 
*/ 
#def ine COPNPRG 0x01 /* open in progress al] others must sleep */ 
#define COPNSLP 0x02 /* sleeping for chance to open */ 
fdefine COPENREAD 0x04 /* open for read only */ 
fdefine COPENWRITE 0x08 /* open for write only */ 
[tencccnencnnnn nn nnn enn e renew neem eee e ee ee eee cn nnn e nen n eee e nwo ce nen eeeeee 
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#define CCISLP 0x01 /* sleeping for channel init ack */ 
fdefine COSLP 0x02 /* sleeping for output to drain */ 

#define COPEN 0x04 /* channel is ready for output (open) */ 
#define CBUSY 0x08 /* channel is busy doing output */ 

#define CCIWAIT 0x10 /* waiting for a chan init ack */ 

#define CCLSSLP 0x20 /* sleeping for close, output must drain */ 
#define CINSLP 0x40 /* sleeping for input queue to fill */ 


#ifndef CPRI 


#define CPRI 29 /* defined in Iprio.h priority level to sleep */ 
fendif 
[Bannnccenennnnnnnn nnn ence nn nnee nner nnn nnenn enna nennennnennconnneroneros 
* Water marking characteristics. 
© cee ecw cee ewe ween wmwwcc cece www ecoees coos cocecesessecoecosceseworrensoree 
a 
#define CLOWATER64 /* low water mark on clout */ 
#define CHIWATER256 /* hi water mark on clout */ 
#define CFEW 16 /* characters are added to clout 8 few */ 
/* at atime. This is a few */ 
[tonewneneen ance nneen nnn nnn neem nee nnne nnn nnneneennnonnronnccosscosscons 
* hpsio firmware command io parameter buffer, one for each channel 
Wo ewww eee w cee www cee wen cww cw ewe encore esos coceseosesecoscsocesn wae seeneee 
*) 
struct ciopb 
{ 
unsigned char func; /* function code */ 
unsigned char stat; /* return status */ 
unsigned char chan; /* channel # */ 
unsigned char cbhaud; /* transmission rate, signal contro) */ 
unsigned char cmodel ; /* parity type, char length */ 
unsigned char cmode2 ; /* #stop bits, Op. mode */ 
unsigned char cstat; /* line status */ 
unsigned char icntri; /* Interrupt Control/SRQ */ 
unsigned char dstat; /* character status */ 
unsigned char dchar; /* received character */ 
char * bufad; /* buffer start address */ 
unsigned short buflen; /* buffer length */ 
}; 
struct ciopb_io 
{ 
struct ciopb input; /* fopb used for channel init and input */ 


struct ciopb output; /* iopb used for output */ 


i] 


[*awwccccenccccenecen enone nnn eeeeeenwenreneeeenannnnanonncocecenncncsnners 
* HPSIO register description 
es oer nnn ee earn 
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a! 
struct cdev 
{ 
Struct ciopb *mailbox; /* mailbox register */ 
unsigned short intrvector; /* interrupt vector */ 
unsigned short arb; /* arbitration / status register */ 
}; 
| eae 
* values for the interrupt vector register of HPSIO (hp->intrvector) 
*/ : : 
#define CINTLEVEL 0x2 /* interrupt level fe spl2() */ 
#def ine CVECTOR 0x70 /* interrupt vector number to use */ 
#define spl_c() spl2() /* should be changed with CINTLEVEL */ 
[ Wiceseceteceecessetacecdect Jansdaseubtnianestuadencsnssuncansensaneuaneas 
* values for the arbitration register of HPSIO (hp->arb) 
BC owocveesvesevesouascceeuseuesse Gudessuacwe eeseencece Se eeaceeteewuouseecwee ace 
a | 
#def ine CREGBASE (struct cdev *) Ox1f1400 /* base address of registers */ 
#def ine CPMCPENDOx02 /* arbitrator bit */ 
fdefine COACKI 0x40 /* arbitrator bit */ 
#define CO_REQ2 0x80 /* arbitrator bit */ 
[Becwewennnncenenecennenenccennenenconnceneeeeneceeeeceewceeneenenseocese 
* function codes 
Cio oO OSS SS CH OSSSESS5E556S 465556 S666 46S SS SESSSSSSEEKED EDO EES ESS SEEDED CREDO 
a i 
fdefine CFCHANINIT 1 /* channel initialization */ 
#define CFCHARACK 2 /* character acknowledgement */ 
#define CFCONINT 3 /* configure interrupt */ 
#define CFOUTPUT 4 /* output */ 
[toccncwcccccnccwceneen enn nn eww een e ene nnwe wen ccn wren ee cweecencccecceccces 
* returned status codes 
& Cweecceeee ere ee rece wceewocceswe sos eceseesoeuceserecoescecoeecoceccoecoesoecco 
a 
#def ine CSOPCPL 0x0 /* operation complete */ 
#define CSCHEK Oxl /* cecksum error on download */ 
#def ine CSBUFAD 0x2 /* bad BUFAD address */ 
fdefine CSMALF 0x3 /* Controller malfunction */ 
fdef ine CSBUSERROx4 /* HPSIO Bus Error */ 
#define CSFUNC 0x5 /* Bad Func code */ 
#def ine CSBUFLENOx6 /* bad BUFLEN count */ 
#define CSTIME 0x7 /* Time out before Tx ready */ 
#def ine CSPARITY0x8 /* HPSIO parity error */ 
édefine CSINT 0x9 /* HPSIO processor unexpected interrupt */ 
#def ine CSDUART Oxa /* Unexpected DUART interrupt */ 
édef ine CSADOR Oxb /* HPSIO processor address error */*/ 
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#def ine CSSERVREQ Oxc /* service request */ 

#define CSCHAN Oxd /* bad CHAN number */ 

#define CSCHANINIT  Oxe /* invalid function t111 channel init */ 
#def ine CSDOWN Oxf /* download in progress */ 

[Son nnn nnn ne nnn nnn n ween enero nnn n nee n nn eee ene nnn e nnn nnnnennnnennenencons 
* yalues of icntr] that are needed 

Br cece cc come e mec wc cc eee ec ces cee we cosas ewsseceeneeosenseeesweresesesewooe 
*/ 

#def ine CRCVSR 0x04 /* received character interrupt */ 

[to nn nnn nnn cnn nnn nnn n ence ence n nnn n neem nn ee een new wen nen nnn ennennnenorees 
* other stuff thats needed 

Wr cc wc cmc eww ewe ecw wc wc cw wc cw ce wee w cece cceececocosownmescccescoesoecoonsccos 
*/ 


#ifndef TRUE 

# define TRUE 1 

fendif 

#ifndef FALSE 

# define FALSE 0 

fendif 

#ifndef min 

# define min(a,b) (a>b 2b: a) 
fendif 
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INTRODUCTION 


The Device Independent Kernel is the software layer above the 
device driver. 


Device Independent Kernel] 
Device Drivers 


Figure 9.1. Kernel Layers 


The kernel contains a layer of software, called Line Discipline 
Routines (LDR), that simplify the creation of terminal device 
drivers. The existing LDR identified as LDRO is described in 
termio(7) in the Administration Reference Manual. 


The device driver is concerned with low-level device-specific 
functions, and the LDR are concerned with high-level device- 
independent functions. 


The Device Independent Kernel communicates with the device 
driver through the LDR. The LDR and the driver functions are 
closely related, but the driver is primarily concerned with handling 
interrupts and setting terminal characteristics. 


Device Independent Kernel | 


LDR 


Device Drivers 


Figure 9.2. Kernel Layers Including LDR 
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A user can write an LDR and substitute it into the kernel with no 
change to the existing drivers. 


EXAMPLE OF LDR FUNCTIONS 


Here are some LDR functions: 


¢ Echo characters entered on a terminal keyboard. 


Input character processing. 


e Delete character processing. 


Delete line processing. 


Signal handling 


¢« Process suspension until a specific time limit has expired, or 
a character is entered, or a line is entered. 


New line character interpretation. 


Delay timing insertion for older devices. 


A general description of tty drivers is provided in the following 
sections. The NEC driver, which controls port A and port B on the 
PMC board, is described to provide specific device driver 
examples. 


NOTE: The regs box in the device (Figure 9.3) is a set of 
registers used by the driver to control the device. 
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KERNEL 


Application 
Program 


Device 
Independent 


Kernel TERMINAL (MINOR) 


Line 
Discipline 
Routines 
(LOR) 


DEVICE (MAJOR) 


Actual Device 
Driver 


Figure 9.3. Relationship Between Software and Hardware 


GENERAL CONTROL FLOW 


Initialization is performed to set up hardware parameters. Codes 
are written to control registers to set characteristics such as parity, 
bits per character, interrupt initialization, etc. The following lists 
identify input and output functions. 


Input: 


e The user enters a character and the terminal transmits that 
character as a serial stream of bits. 
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¢ The bits are received by the device and assembled into a 
character. 


e The character is examined for validity by the device. 
e The character is put into the receive buffer register. 
e An interrupt is generated. 


e The receive Interrupt Service Routine (ISR) in the driver is 
invoked. 


Output: 

e When the transmitter portion of the device is on, and a 
character has been placed in the transmit buffer register by 
the driver, the character is converted to a stream of bits and 
sent to the terminal. 


* When the transmit buffer register becomes empty, an 
interrupt is generated. 


e The transmit ISR in the driver is invoked to write another 
character to the device. 


NEC TERMINAL CONTROLLER 


Figure 9.4. NEC Chip Block Diagram 
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Figure 9.4 shows that the nec chip has two registers associated 
with each channel. Reading or writing these registers controls the 
NEC chip in this way: 


¢ Reading from a dbuf (data buffer register) returns the value of 
the oldest character stored in the chip’s three character fifo 
queue. 


¢ Writing to a dbuf causes a character to be transmitted to the 
terminal. 


¢ To obtain status information about the chip, the driver must 
read from a csr (control status register). 


¢ To control the hardware parameters of the chip, the driver 
must write to a csr (control status register). 


This C declaration defines the device: 


struct device 
{ 
char _ dbuf, 
char dumt1; 
char csr; 
char dume2; 
le 


struct device *nec_addr = (struct device*)0xe00101; 


NOTE: The hex address used in the example applies 
only to the 16-bit machines. 


To read a character from port A, execute this C statement: 
ch = nec_addr->dbuf; 
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A| CRO CR1 CR2 CR3 CR4 CRS CRE CR7 SRO SR1 SR2 
B| CRO CRi CR2 CR3 CR4 CRS CRE CR7 SRO SRi SR2 


Figure 9.5. NEC Chip Registers 


The control status register (csr) is used to access eight internal 
control registers and three internal status registers. By default, 
control/status register zero is manipulated. The lower three 
significant bits in control register zero are used as a register 
pointer. The following C_ statements writes configuration 
information to control register two: 


#define RP22 
#define NON_VECTOR 0 


nec_addr->csr = RP2; 
nec_addr->csr = NON_VECTOR; 


NOTE: The remaining details of the NEC chip are described 
as required. 
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DATA FLOW DIAGRAM 


Figure 9.6 describes the data flow for the NEC driver. 


Canonical Raw Input Output 
Application e Driver 


Figure 9.6. NEC Driver Data Flow 


NOTE: The canonical input queue, raw input queue, and 
output queue are all controlled by the LDR. The queues are 
not accessed by the device driver. 


The t_rbuf and t_tbuf are the receive character buffer and transmit 
character buffer. These buffers are used to pass character buffers 
between the driver and the LDR. For example, t_rbuf is partially 
filed by the receive ISR of the device driver. An LDR function is 
called to process the characters in the buffer. 
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Control Flow 


Primary events, related driver and LDR functions are shown in 
Figure 9.7. 


ENTRY POINT DRIVER FUNCTION LDR FUNCTION 


upper layers necopen 1_open 


t_topen 


upper layers necioct | 


upper layers not used 1_mdmint 


Figure 9.7. Driver/LDR Functions 


The kernel is configured so that /_read and /_write are called 
directly and necread and necwrite are never called. 


LINE SWITCH TABLE 


The line switch table defines entry points into the LDR and is 
similar in structure to the block device switch table and the 
character device switch table. The line switch table is defined in 
/usr/include/sys/cont.h. 


{* 
* Line discipline switch. 
i 
struct linesw { 
int (*1open)(); | /* on open to a minor device */ 
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int (*l_close)(); /* after all closes to a minor device */ 
int (*l_read)(); /* on a read system call */ 

int (*lwrite)();  /* on a write system call */ 

int (*1_foct1)(); /* on a foct] system call */ 

int (*linput)(); /* from driver's receiver ISR */ 

int (*l_output)(); /* from driver's transmitter ISR */ 

int (*l_mdmint)(); /* from driver on modem status change */ 


3? 


extern struct linesw linesw[]; 


extern int linecnt; 


This data structure permits multiple LDRs to exist in the kernel, 
and each terminal or aoplication can choose which LDR to use. 


TTY STRUCTURE 


A tty structure exists for each terminal (minor device) in the 
system. All data needed to monitor the terminal status are kept 
the tty structure. The tty structure is defined in 
/usr/include/sys/tty.h. 


struct cceblock { 


caddr_t c ptr; /* buffer address = */ 
ushort c_count; /* character count */ 
ushort c_size; /* buffer size =} 


}; 


fdefine NCC 8 

struct tty { 
struct clist t_rawq; /* raw input queue */ 
struct clist t_canq; /* canonical queue */ 
struct Clist t_outq; /* output queue */ 
struct ccblock t_tbuf; /* tx control block */ 
struct ccebiock t_rbuf; /* rx control block */ 
int (* t_proc)();  /* routine for device functions */ 
ushort t_iflag; /* input modes */ 
ushort t_ofiag; /* output modes */ 
ushort t_cflag; /* control modes */ 
ushort t_Iflag; /* line discipline modes */ 
long t_state; /* internal state */ 


short t_porp; /* process group pid */ 
shortt_delct; /* delimiter count */ 

char t_iine; /* line discipline */ 
char t_term; /* termina) type */ 
char t_taflag; /* terminal flags */ 

char t_col; /* current column */ 
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char t_row; /* current row */ 
char t_vrow; /* variable row */ 
char t_lrow; /* last physical row */ 


char t_hqcent; /* no. high queue packets on t_outq */ 
char t_dstat; /* used by terminal handlers 
and line disciplines */ 
unsigned char t_cc[NCC); /* settable control chars */ 
}; 


The fields in the tty structure used by the device driver are 
described below. The remaining fields are used only by the LDR. 


t_tbuf Transmit buffer. This buffer is filled by the LDR and 
emptied by the driver. The LDR function /_ output fills 
this buffer. 


t_rbuf Receive buffer. This buffer is filled by the driver. The 
LDR function /_ input processes this buffer. 


t proc Driver procedure. This identifies a function that can 
be called by the LDR to change the state of the 
driver. 


t_iflag Input mode bit flags. Specifies input control. 


These flags are used by the driver: 


IXON XON/XOFF output flow control. 

IXOFF XON/XOFF input flow control 

IXANY Use any character to start output flow, not just 
<control q>. 

IRTS Use the request-to-send signal to start and stop the 


input flow from the terminal. 
PARMRK Mark parity framing and overrun errors. 


IGNBRK ignore break characters. 
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BRKINT Send a signal to all processes associated with the 
terminal when a break character is received. 


INPCK Enable the use of parity checking for input and output 
characters. 


IGNPAR Ignore parity on input. This permits output parity to 
be generated while ignoring input parity errors. 


ISTRIP Strip off most significant bit of eight bit character. 
ERR_BEL Transmit a bell on errors. 


t cflag Control bit flags. Used to specify the hardware 
configuration of the device. 


t state State of the terminal device bit flags. 

These flags are used by the driver: 

WOPEN Waiting to open. The open function of the driver has 
been called but it isn’t open yet. it may be 
suspended, waiting for a terminal or modem to be 
turned on. 

ISOPEN The terminal is open. 

CARR_ON_ The carrier was detected (ON). 

BUSY The driver is busy performing output. When in this 
state, an interrupt occurs after the character is 


transmitted and the device is unable to accept more 
characters to transmit. 


OASLP The LDR routines are asleep waiting for output to 
complete. 


TTXON A XON character needs to be transmitted by the 
transmit interrupt routine. 
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TTXOFF A XOFF character needs to be transmitted by the 
transmit interrupt routine. 


TIMEOUT The device is busy for a specific period of time. No 
characters should be transmitted when this flag is on. 


TTSTOP Output is stopped (suspended). No _ characters 
should be transmitted when this flag is on. 


TBLOCK Input is stopped (blocked). 


t_line Line discipline identification. A number 
corresponding to the line discipline routines being 
used. This is an index into the /inesw table. 


RS-232-C HARDWARE SIGNALS: DTR AND DCD 


RS-232-C is an industry standard that describes the interface 
between a computer and a modem (DTE to DCE). A small subset 
of this standard is used by the NEC chip. The device driver can 
set or sense certain pins in the RS-232 connector between the 
device controller and the terminal. The DTR and DCD signals 
show existence of a device in two ways: 


¢ DTR (Data Terminal Ready) notifies the terminal that the 
computer is turned on. DTR is enabled at the first open of 
the minor device and remains ON. 

¢ DCD (Data Carrier Detect) notifies the computer that the 


terminal is turned on. Normally, DCD is enabled when the 
terminal power switch is turned on. 


NECOPEN DEFINITION 
The open routine performs these functions: 


¢ The internal representation of carrier is turned on or off. 
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« The routine sleeps until carrier is detected, unless this option 
is overridden by the open flag. 


¢ The LDR /_ open routine is called. 


¢ The first open for a device executes the LDR, ttinit, to set up 
flag default hardware configuration values. 


NECOPEN LISTING 


s 


void necopen(minor_d, flag) 


dev_t minor_d; /* minor device number */ 
int flag; 
{ 
register struct tty *tp; 
struct device *rp = nec_addr + minor_d; 
int priority ; 
extern int necproc() ; 


if ( minor_d >= nec_cnt ) 
{ 
u.u_error = ENXI0; 
return; 
} 

necsave(“necopen 2"); 

tp = &nec_tty[minor_d]; 


if ((tp->t_statek(ISOPEN|WOPEN)) == 0) 
{ 
ttinit(tp); 
tp->t_proc = necproc; 
necparam(minor_d); 
} 
if( rp->csr&DCD ) 
tp->t_state j= CARR_ON ; 
else 
tp->t_state &= “CARR ON ; 


if ( \(flag & FNDELAY) ) 


{ 
priority = sp13() ; 


/* open flag see fopen.h */ 
/* nec tty to initialize */ 
/* nec register pointer */ 

/* previous priority */ 

/* state changes by LOR */ 


/* minor number within range */ 


/* initialize tty pointer */ 
/* first open for device */ 


/* set default termio flags */ 


/* LOR needs state change proc */ 
/* initialize HW as set by ttinit */ 


/* if OCD then we're ready */ 
/* set carrier on flag */ 


/* carrier is not on */ 


/* the user wants to wait */ 


/* until carrier is detected */ 


while( (tp->t_state&CARR_ON) == 0 ) /* until carrier is on */ 
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{ 
tp->t_state j= WOPEN ; /* we are waiting to open */ 
sleep((caddr_t)&tp->t_cang, TTIPRI ) ; /* and sleeping */ 
} 
sp1x (priority) ; 


} 
/* set up process groups. mark terminal as ISOPEN. set up t_rbuf. */ 
(*1inesw[tp->t_line].1_open)(tp); /* call necproc(tp, T_INPUT) */ 


DEVICE DRIVER INTERRUPT SERVICE ROUTINES 


Two interrupt service routines (ISR) are used to handle interrupts 
generated by a device. 


Receive interrupt service routine: 


¢ Reads the status register to check for errors (framing, 
overrun, or parity). 


e Reads the receive buffer register. 
¢ Resets interrupts. 


¢ If t_rbuf has been initialized, puts the character read into 
t_rbuf and calls the LDR input interrupt function. 


Transmit interrupt service routine: 
¢ Resets transmit interrupts. 


¢ If there are characters in t_tbuf, takes the next character from 
t_tbuf. 


« Writes the character to the device transmit buffer register or 
calls the LDR function to put more characters in t_tbuf. 


T_rbuf 


The receive buffer is filled by the device driver and passed to the 
|_input routine of the LDR for processing. 
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struct ccblock { 
caddr tt c_ptr, /* buffer address */ 
ushort c_count; /* character count */ 


ushort c_size; //* buffer size */ 
}5 
WHERE: 
Cc ptr Pointer to a buffer where received characters can be 
placed. 


c_count Amount of space leit in buffer. Initially the same as 
c_size. Decremented each time a character is added 
to the t_rbuf. 


c_size Size of the buffer. Never changed by the driver. 
T_rbuf can be in one of four states: 


Uninitialized state 
The LDR routine /_input needs to be called to initialize 
t_rbuf. C_pir is 0 when in this state. All received characters 
should be ignored when in this state. 

Empty state 
When in this state the driver has not started filling t_rbuf. 
C_pir has been initialized by the LDR to point to an empty 
buffer. C_size and c_count are initially both the same value 
(CLSIZE). 

Filling state 
When in this state, the driver is in the process of filling the 
t_rbuf. Each character is put into the buffer. C count 
needs to be decremented at the same time. 

Full state 
When the buffer becomes full or when the receive ISR has 
read all characters for a given interrupt, the buffer pointer is 
reset and the LDR /_input routine is called. 
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T_tbuf 


The transmit buffer is filled by the LDR /_output routine and is 
passed to the device driver for writing to the device. 


c__ptr 
c__count = 64 
c_size = 64 


Figure 9.8. Buffer Empty 


struct ccblock { 
caddr t c_ptr /* buffer address ‘*/ 
ushort c_count; /* character count */ 


ushort c_size; /* buffer size */ 
} 
WHERE: 
c_pitr Pointer to a buffer of characters. 


c_count Number of characters left in buffer. Initially the same as 
c_size. Decremented each time a_ character is 
transmitted. 


c_size Size of the buffer. Never changed by the driver. 
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*cptr+ + = data__register 
- —C__count: 


c__ptr 
c_count = 63 
c__size = 64 


Figure 9.9. Buffer Filling 
T_tbuf can be in one of four states. 


Uninitialized state 
The line discipline routine /_ output needs to be called to 
initialize t_tbuf. C_pér is 0 or c_size is 0 when in this state. 
Full state 
When in this state the driver has not started emptying t_tbuf. 
C_ptr has been initialized by the LDR to point to a buffer. 
C_size and c_count are initially both the size of the buffer. 


cptr - = c_size — c__count; 


c__ptr 
c__count = 62 
c_size = 64 


Figure 9.10. Ail Characters Received 
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Transmitting state 


When in this state, the driver is in the process of transmitting 


the ¢_tbuf. 


c__ptr 
c_count = 12 
c_size = 12 


Figure 9.11. Buffer Initialized 


data_register = ‘cptr+ +; 
- -C__count; 


c__ptr 
c_count = 9 
c_size = 12 


Figure 9.12. Buffer Transmitting 
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Empty state 


When the buffer becomes empty, the c_pir value is reset 
and the /_ output LDR routine is called to get another buffer. 


cptr - = C__size - c__count; 


c__ptr 
c__count = 0 
c_size = 11 


Cam ase a= ew em as ass ow am aw aw am ow & 


Figure 9.13. Buffer Empty 


RECEIVER/TRANSMITTER LISTING 


/* Variable Definition 

* rp - register pointer for the port 

* nec_addr - register pointer to port A 

* tp - pointer to tty structure for the interrupting terminal 
se 


/* Receiver interrupt service routine */ 
rp->csr = RP]; /* check for errors */ 
if ( rp->csr & SP_FLAGS ) /* Framing, Overrun, Parity */ 
goto SRCOND ; 


c = rp->dbuf; /* read a character */ 


rp->csr = RINT RESET; /* reset interrupts */ 
nec_addr->csr = END INT ; 


if ( tp->t_rbuf.c_ptr *=* NULL ). /* why not check for c_count == 0 */ 
continue ; 
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*tp->t_rbuf.c_ptr++ = c ; /* stash character in t_rbuf */ 
--tp->t_rbuf.c_count ; 

/* adjust c_ptr correctly */ 
tp->t_rbuf.c_ptr -= tp->t_rbuf.c_size - tp->t_rbuf.c_count; 
(*linesw[tp->t_line].1_input)(tp) ; /* LOR input */ 


/* Transmitter interrupt service routine */ 


rp->csr = PENDING_XINT_RESET ; /* reset interrupts */ 


nec_addr->csr © END_INT ; /* Done with interrupt */ 
tbuf = &tp->t_tbuf; /* initialize to transmit buffer */ 
if( tbuf->c_ptr le NULL && tbuf->c_count I= 0 ) 
{ /* 4f there is something to xmit */ 
tbuf->c_count--; /* write character */ 
rp->dbuf = *tbuf->c_ptr++; 
} 
else 
{ 


tp->t_state &= “BUSY; /* not busy doing output */ 
necproc(tp,T_OUTPUT) ; /* get another t_buf and prime the pump */ 
} /* by writing the first character */ 


INPUT/OUTPUT FLOW CONTROL 


lf two devices are communicating at different or variable band 
rates, the devices must have a method to start and stop each 
other. Start/stop contro! of a device is called flow control. For 
example, if a computer sends characters to a printer at speeds 
faster than the printer can actually print, the printer stores the 
characters in a local buffer. When the local buffer is almost full, 
the printer must stop the flow of characters so that no characters 


are lost. 
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Printer 
| buffer 
characters 
high water 
low water 


Figure 9.14. Flow Control 
The two common methods of handling I/O flow control are: 
e XON/XOFF flow control 


¢ Ready/Busy flow control 


XON/XOFF Flow Control 
The XON/XOFF protocol uses reserved characters within the 
data stream that have special meaning and are not data 
characters: XOFF is a stop character and XON is a start 
character. 


Characters are transmitted to the printer at a rate faster than 
— the printer can print. The printer stores characters in its 
internal (local) buffer. When the buffer reaches a high water 
mark, the printer transmits an XOFF character to the 
computer. The computer must stop transmitting characters. 
The printer continues to print the characters in the buffer 
until a low water mark is reached, at which time the printer 


. 
| 


| 


UP-12230 R1 9-21 


Chapter 9 


SE I NE ET a Le A 


transmits a XON character. The computer can then resume 
sending characters. 


XON/XOFF Protocol for Output Flow Control 
The output flow of characters from the computer to the 
printer is controlled by the printer. The device driver 
handles output flow control. 


The t_iflag in the tty structure has a bit flag which shows that 
XON/XOFF output flow control is being used. If (t_iflag & 
IXON) is true, the protocol is active. 


The routine that detects a change in the state of output flow 
control is the receive ISR. The receive ISR algorithm has to 
be modified like this: 


Read the status register to check for errors (framing, 
overrun, or parity). 


Read the receive buffer register. 


Reset interrupts. 


If the character is a XOFF character, SUSPEND output. 


If the character is a XON character, RESUME output. 


If t_rbuf has been initialized, put the character read 
into t_rbuf and call the LDR input interrupt function. 


RECEIVE ISR LISTING 


while(rp->csr & CHAR_AVAILABLE) /* while characters to receive */ 
{ 


rp->csr = RPI; /* check for errors */ 

if ( rp->csr & SP_FLAGS ) /* Framing, Overrun, Parity */ 
goto SRCOND ; 

c = rp->dbuf; /* read @ character */ 

rp->csr = RINT_RESET; /* reset interrupts */ 


nec_addr->csr ° END_INT ; 
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/* begin XON/XOFF output flow contro] section */ 
{f (tp->t_iflag & IXON) 


{ 
register char ctm; /* way be an XON or XOFF char */ 
ctm = c & 0177; 
if (tp->t_state & TTSTOP) /* output is suspended */ 
{ /* resume on start character */ 
if (ctmp == CSTART || tp->t_if lag&IXANY) 
(*tp->t_proc)(tp, T_RESUME) ; 
} 
else 
{ 
if (ctmp == CSTOP) /* stop character received */ 
(*tp->t_proc)(tp, T_SUSPEND) ; /* suspend output */ 
} 


/* start/stop chars go no further */ 
if (ctmp == CSTART || ctmp == CSTOP) 
continue ; 


} 
/* end XON/XOFF output flow control section */ 


/* stash character in r_buf */ 
if ( tp->t_rbuf.c_ptr == NULL ) /* why not check for c_count == 0 */ 
continue ; 


*tp->t_rbuf.c_ptre+ = ; 
--tp->t_rbuf.c_count ; 


/* adjust c_ptr correctly */ 
tp->t_rbuf.c_ptr -= tp->t_rbuf.c_size - tp->t_rbuf.c_count; 
(*linesw[tp->t_line].1_input)(tp) ; /* LOR input */ 

} 
break; 


XON/XOFF PROTOCOL FOR INPUT FLOW CONTROL 


The computer also controls the flow of input characters from fast 
peripherals using the XON/XOFF protocol, if (t_iflag & IXOFF) is 
true. 


When the computer wants to stop the peripheral from sending 
characters, it transmits an XOFF character. This function is called 
BLOCKing input. When the computer is capable of receiving 
characters, it transmits an XON character. This function is called 
UNBLOCKing input. The BLOCKing and UNBLOCKing state is 
detected by the LDR, which uses a water marking scheme on the 
raw input queue. 
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The state transition could occur when the device is busy. If the 
device is busy, the t_state flags TTXON or TTXOFF are set, 
indicating that an XON or an XOFF needs to be sent at the next 
invocation of the transmit ISR. 


The transmit interrupt service routine algorithm includes these 
functions: 


¢ Reset transmit interrupts. 


e Write an XON to the transmit buffer register if the TTXON flag 
is set. 


e Write an XOFF to the transmit buffer register if the TTXOFF 
flag is set. 


¢ If there are characters in t_tbuf. 
1. Take the next character from t_tbuf. 


2. Write the character to the device transmit buffer 
register. 


3. Else call the LDR function to put more characters in 
t tbuf. 


TRANSMITTER ISR LISTING 


* pnec.xint.c -- transmit interrupt handler, include file 
* on input. Interrupts are turned off. T_state is marked as BUSY. 
* rp is pointing to the correct register set for a or b. 


af 

rp->csr = PENDING_XINT_RESET ; /* reset interrupts */ 

nec_addr->csr = END_INT ; /* Done with interrupt */ 
sysinfo.xmtint++ ; /* increment tallies in sysinfo */ 


check_tally( chan, T_OUTS ) ; 


if ( tp->t_state & TTXON ) /* If waiting to transmit */ 
{ /* XON state */ 
tp->t_state &= “TIXON ; /* clear XON state */ 
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rp->dbuf = nec_xon ; /* write a XON character */ 
} 

else if (tp->t_state & TTXOFF ) /* If waiting to transmit */ 

nm { /* XOFF state */ 

tp->t_state &= “TTXOFF; /* clear XOFF state */ 
rp->dbuf = nec_xoff ; /* write a XOFF character */ 
} 

else /* normal character can be output */ 
{ 


register struct ccblock *tbuf; /* point to transmit buffer */ 


if( tp->t_state & TTSTOP ) /* output is suspended <ctr] s> */ 


{ 
tp->t_state &= “BUSY; /* not busy doing output */ 
continue ; 


} 

tbuf = &tp->t_tbuf; /* initialize to transmit buffer */ 

if( tbuf->c_ptr I= NULL && tbuf->c_count I= 0 ) 
{ /* if there is something to xmit */ 
tbuf->c_count--; /* write character */ 
rp->dbuf = *tbuf->c_ptr++; 
} 

f™ else 

{ 


tp->t_state &= “BUSY; /* not busy doing output */ 
necproc(tp,T_OUTPUT) ; /* get another t_buf and prime the pump */ 


} /* by writing the first character */ 
} 
break ; 
READY/BUSY FLOW CONTROL 


The ready/busy flow control protocol is similar to XON/XOFF. RS- 
232C signals are used to control the flow of characters. The 
Request-To-Send (RTS) pin of the NEC controller is controlled by 
the device driver and can be used by the device driver for input 


flow control. 
e When RTS is enabled, the terminal can transmit characters 


e When ARTS is disabled, the terminal cannot transmit 
characters. 
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The peripheral device uses a signal electrically connected to 
the clear to send (CTS) pin on the NEC controller. The driver 
doesn’t participate in output flow control. 


« When CTS is enabled, characters can be transmitted by the 
NEC controller. 


e When CTS is disabled, characters can’t be transmitted by the 
NEC contoller. | 


The NEC controller stops transmitting characters when the 
CTS pin is disabled and stops generating interrupts. 
Therefore, the device driver does not participate in 
ready/busy input flow control. 


PARITY 
- Incoming characters may have a parity bit appended to the input 
character. If parity is enabled, the receiver ISR must clear this bit 
before storing it in the t_rbuf. 
The driver can be put in a mode (t_iflag & PARMRK) where 
characters received with parity, framing, or overrun errors are 
placed in t_rbuf, as shown in this three character sequence: 

0377 0x 


NOTE: xis the character received in error. 


lf the receiver ISR gets a natural 0377 character, the 0377 should 
be substituted with the two character sequence 0377 0377. 


RECEIVER ISR LISTING 


* pnec.rint.c -- receive isr, interrupts turned off, may or may 
* not be a place to put the characters 


y 


sysinfo.rcvint++ ; /* increment tallies in sysinfo */ 
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while(rp->csr & CHAR AVAILABLE) /* while characters to receive */ 
‘ 


rp->csr = RP1; /* check for errors */ 
if ( rp->csr & SP_FLAGS ) /* Framing, Overrun, Parity */ 
goto SRCOND ; 


c = rp->dbuf; /* read a character */ 
rp->csr = RINT_RESET; /* reset interrupts */ 
nec_addr->csr = END_INT ; 


check_tally(chan, T_INPUTS); 


if( !(tp->t_state & (ISOPEN|WOPEN)) ) /* {f not open(ing) forget it */ 
continue ; 


/* — begin XON/XOFF output flow control section */ 
if (tp->t_iflag & IXON) 


{ 
register char ctmp; /* may be an XON or XOFF char */ 
ctmp = c & 0177; 
if (tp->t_state & TTSTOP) /* output is suspended */ 
{ /* resume on start character */ 
if (ctmp == CSTART |} tp->t_if lag&IXANY) 
(*tp->t_proc)(tp, T_RESUME) ; 
} 
else 
{ 
if (ctmp == CSTOP) /* stop character received */ 
{ 
nec_addr->csr = NON_VECTOR; 
(*tp->t_proc)(tp, T_SUSPEND) ; /* suspend output */ 
} 
} /* start/stop chars go no further */ 


if (ctmp == CSTART |} ctmp == CSTOP) 
continue ; 


} 
/* end XON/XOFF output flow control section */ 


/* stash character in t_rbuf */ 
if ( tp->t_rbuf.c_ptr == NULL ) /* why not check for c_count == 0 */ 


continue ; 


if (tp->t_cflag & PARENB) /* strip off parity bit(s) if parity enabled ey 


{ 
switch (tp->t_cflag & CSIZE) /* number of bits in character */ 
{ 
case CS7: 
c & 0x7f; 
break; 
case CS6: 
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c &= O0x3f; 

break; 
case CS5: 

c & Oxlf; 

break; 


} 


*tp->t_rbuf.c_ptr++ = Cc ; 
--tp->t_rbuf.c_count ; 


if ( ¢ == 0377 && tp->t_if lag&PARMRK ) /* 0377 is 0377 0377 */ 


{ /* this avoids ambiguity */ 
*tp->t_rbuf.c_ptr++ = 0377 ; /* when parity errors are marked */ 
--tp->t_rbuf.c_count ; /* and passed to the LOR */ 

} 


/* adjust c_ptr correctly */ 
tp->t_rbuf.c_ptr -= tp->t_rbuf.c_size - tp->t_rbuf.c_count; 
(*linesw[tp->t_line].1_input)(tp) ; /* LDR input */ 

} 


break; 


ISTRIP 


The last addition to the receiver interrupt routine is the ISTRIP 
input option. If ISTRIP is set, valid input characters are first 
stripped to 7 bits; otherwise, all 8 bits are processed. 


RECEIVER ISR -- FINAL VERSION 


* pnec.rint.c -- receive isr, interrupts turned off, may or may 
* not be a place to put the characters 


*} 
sysinfo.rcvintt++ ; /* increment tallies in sysinfo */ 
while(rp->csr & CHAR_AVAILABLE) /* while characters to receive */ 

{ 

rp->csr = RP1; /* check for errors */ 


if ( rp->csr & SP_FLAGS ) /* Framing, Overrun, Parity */ 
goto SRCOND ; 


c = rp->dbuf ; /* read a character */ 


rp->csr = RINT RESET; /* reset interrupts */ 
nec_addr->csr = END_INT ; 
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check_tally(chan, T_INPUTS); 


if( !(tp->t_state & (ISOPEN}WOPEN)) ) /* if not open(ing) forget it */ 
continue ; 


begin XON/XOFF output flow control section */ 
if (tp->t_iflag & IXON) 
{ 
register char ctmp; /* may be an XON or XOFF char */ 
ctmp = c & 0177; 
if (tp->t_state & TTSTOP) /* output is suspended */ 
{ /* resume on start character */ 
if (ctmp == CSTART || tp->t_if lag&IXANY) 
(*tp->t_proc)(tp, T_RESUME) ; 


else 


if (ctmp == CSTOP) /* stop character received */ 
(*tp->t_proc)(tp, T_SUSPEND) ; /* suspend output */ 
} 
/* start/stop chars go no further */ 
if (ctmp == CSTART |}! ctmp == CSTOP) 
continue ; 


} 
end XON/XOFF output flow control section */ 


/* stash character in r_buf */ 
if ( tp->t_rbuf.c_ptr == NULL ) /* why not check for c_count == 0 */ 
continue ; 


if (tp->t_cflag & PARENB) /* strip off parity bit(s) if parity enabled */ 
{ 
switch (tp->t_cflag & CSIZE) /* number of bits in character */ 
{ 
case CS7: 
c & Ox7f; 
break; 
case CS6: 
c & 0x3f; 
break; 
case CS5: 
c & Oxlf; 
break; 


} 


if (tp->t_iflag & ISTRIP) 
c=c & 0177; 


*tp->t_rbuf.c_ptr+t+ = c ; 
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--tp->t_rbuf.c_count ; 


if ( c == 0377 && tp->t_iflag&PARMRK ) /* 0377 is 0377 0377 */ 


{ /* this avoids ambiguity */ 

*tp->t_rbuf.c_ptr++ = 0377 ; /* when parity errors are marked */ 

--tp->t_rbuf.c_count ; /* and passed to the LDR */ , 
2 x, P N } 


/* adjust c_ptr correctly */ 


tp->t_rbuf.c_ptr -= tp->t_rbuf.c_size - tp->t_rbuf.c_count; 
(*linesw[tp->t_line].1_input)(tp) ; /* LOR input */ 


} 


break; 


LDR TO DRIVER COMMUNICATION 


The LDR, not the driver, contains the information to determine 
when input flow should be stopped or started. The LDR calls the 
device driver which implements the input flow control. There are a 
number of other times when the LDR needs to communicate with 
the driver. The driver proc routine is used for LDR to driver 
communication. The entry points in the proc routine that must be 
provided are: 


Starting output 
Suspending output 
Resuming output 
Breaking transmission 
Transmitting buffer flush 
Receiving buffer flush 


Logging an overrun error 


The format for the proc routine is: 


driverproc(tp, command); 
struct tty * tp; /* tty structure */ 
int command; /* command to be performed */ 
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The name of the routine for the NEC driver is necproc(). 


These commands are handled by the proc routine: 


T OUTPUT Start output to the device. Call the LDR output 
routine to get a t_tbuf if the current buffer is 
empty. 

T_ BLOCK Stop the flow of input. 

T UNBLOCK Start the flow of input. 

T SUSPEND Stop the flow of output. 

T RESUME Start the flow of output. 

T_BREAK Send a break stream to the device for 1/4 


second. Normally this is done by setting a 
hardware status register to send the break and 
scheduling a timeout in 1/4 second. After the 
1/4 second elapses, call necproc(tp, T_ TIME). 


T_TIME Clear the break condition on the device. Start 
output to the device. 


T_WFLUSH Flush the current transmit buffer and start the 
flow of output starting with the next t_tbuf. 


T_RFLUSH If blocked, unblock. If unblocked, return. 


T_LOG_FLUSH Raw input queue overflow has occurred; empty 
read queue and UNBLOCK input. 


NECPROC LISTING 


wf 
necproc(tp, cmd) 
register struct tty *tp; /* tty pointer */ 
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register Cc; 

register struct device *rp; 
int priority ; 

int dev ; 

extern ttrstrt() ; 


dev = tp - nec_tty ; 
rp = nec_addr + dev ; 


switch (cmd) { 


case T_TIME: 
é include "pnec.time.c” 


case T_WFLUSH: 


/* device register pointer */ 
/* priority incomming */ 
/* minor number a=0 b=1 */ 


/* minor is 0 or 1 */ 
/* register pointer set accordingly */ 


/* timeout expiration handler */ 


/* flush transmit buffer note no break */ 


tp->t_tbuf.c_size -= tp->t_tbuf.c_count ; 


tp->t_tbuf.c_count = 0 ; 


case T_RESUME: 
tp->t_state &= “TTSTOP; 


case T_OUTPUT: 
start: 
é include "pnec.output.c" 


case T_SUSPEND: 
tp->t_state |= TTSTOP; 
break; 


case T_BLOCK: 
# include "pnec.block.c" 


case T_RFLUSH: 


/* resume output, note no break */ 
/* clear suspend flag */ 


/* restart output */ 
/* where to go to start transmitting */ 


/* output start handler */ 


/* suspending output is just */ 
/* setting this flag */ 


/* block handler */ 


/* read flush */ 


if (1(tp->t_state&TBLOCK)) /* if blocked unblock */ 


break; 


case T_UNBLOCK: 
# include "pnec.unblock.c" 


case T_BREAK: 
# include "pnec.break.c" 


case T_LOG FLUSH: 


/* unblock handler */ 


/* send a break for 1/4 second */ 
/* break handler */ 


check_tally( dev, T_OVERFLOW ) ; 


break ; 
t 
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DRIVERPROC(TP, T_OUTPUT) 


This routine is called from the LDR to start output. Ifthe device is 
not busy, the routine t:-nsmits a character to start receiver 
interrupts. If the device is busy, a character can not be sent until 
the next receiver ISR. Busy conditions are: 


BUSY The device is in the process of transmitting a 
character. 


TTSTOP The driver is in a output flow control hold state; 
output is suspended. 


TIMEOUT =A certain amount of time must pass before giving the 
device the next character. 


If there are no characters in the t_tbuf to transmit, the LDR 
!_output routine is called to fill the t_tbuf. 


NOTE: This routine is also called from the driver when the 
transmitter ISR routine finds that t_tbuf is empty. 


PNEC.OUTPUT.C LISTING 


* pnec.output.c -- T_OUTPUT routine. Called to start the output 
* from the LDR. Also called from the driver when transmit isr has 
* no characters to transmit. 

* If the transmission of characters is impossible then this routine 
* did not have to be called so return imeadiately. The reasons 

* for not being able to transmit characters are: 

* BUSY - Character is being output 

* TTSTOP - output has been suspended 

* TIMEOUT - output has been stopped for a certain time period 


register struct ccblock *tbuf; /* transmit buffer */ 


priority = spl3() ; 

if( tp->t_state & (TTSTOP|BUSY| TIMEOUT) ) 
{ /* impossible to transmit chars */ 
spix( priority ) ; 

break ; 
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tbuf = &tp->t_tbuf; /* set tbuf to the t_buf */ 
{f( tbuf->c_ptr = NULL || tbuf->c_count == 0 ) 
{ /* need a new t_buf */ 
if( tbuf->c_ptr ) /* if tbuf has been initialized */ 
tbuf->c_ptr -= tbuf->c_size ;  /* reset the buffer pointer a 
/* get another t_buf */ 
if( !(CPRES & (*linesw[tp->t_line].1_output)(tp)) ) 


{ /* if no chars in t_buf */ 
spix( priority ) ; /* there is nothing to transait */ 
break ; /* so quit */ 
} 
} 
if( tbuf->c_count ) /* if there are chars to transmit */ 
/* take one out of tbuf and */ 
tbuf->c_count--; /* transmit it */ 


rp->dbuf = *tbuf->c_ptr++; 
tp->t_state |= BUSY; 


} 
spix( priority ) ; 
break; 
} 


DRIVERPROC(TP, T_BLOCK) 
The functions this routine performs are: 


* Block further input; the high water mark has been reached 
and no further input should be permitted. 


Mark the driver state to show that input is blocked; primarily 
used by the LDR. 


if the ready/busy input flow control protocol is being used, 
stop input by turning off RTS. 


if the XON/XOFF input flow control protocol is being used, 
transmit an XOFF character. If the device is busy, inform the 
transmit ISR to transmit an XOFF character. 
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NECPROC(TP, T_BLOCK) LISTING 


* pnec.block.c -- block the input of characters. 

* XON/XOFF or ready/busy protocol] is allowed 

* XON/XOFF - send a XOFF character or tel] the xmit isr to send one. 
* ready/busy - turn off RTS 


i 
tp->t_state {= TBLOK; /* Let the xmit isr know */ 
tp->t_state $= TTXON; /* clear the send XON flag */ 


if( tp->t_iflag & IRTS ) /* ready/busy stuff */ 


{ 

priority = sp13() ; 

rp->csr = RP5 ; /* turn off RTS */ 
rp->csr = CSR(dev].cr5 = CRS[dev].cr5 & RTS ; 
spIx( priority ) ; 

} 


if( tp->t_state & IXOFF ) /* disable input using XON/XOFF protocol */ 


{ 
priority © spl4() ; 
if( tp->t_state & BUSY ) /* cant send an XOFF no, so */ 
tp->t_state j= TTXOFF ; /* let the xmit interrupt send it */ 
else 
{ /* send the XOFF now */ 
tp->t_state |= BUSY ; 
rp->dbuf = nec_xoff; 
} 
spIx( priority ) 


break; 


DRIVERPROC(TP, T_UNBLOCK) 


The low water mark has been reached so input is permitted. These 
functions are performed: 


e Reset the block flag. 


¢ If ready/busy input flow control protocol is being used, turn 
on RTS. 
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« {f XON/XOFF input flow control protocol is being used, 
transmit an XON character or inform the transmit ISR to 
transmit an XON character. 


PNEC.UNBLOCK.C LISTING 


* pnec.unblock.c -- allow the input of characters. 

* XON/XOFF or ready/busy protocol is allowed 

* XON/XOFF - send a XON character or tel] the xmit isr to send one. 

* randyineny turn on RTS 

*/ 

tp->t_state &= ~(TTXOFF{TBLOCK); /* clear block state and no XOFF to send */ 


if( tp->t_iflag & IRTS ) /* ready busy stuff */ 


{ 

priority = spi3() ; 

rp->csr = RPS ; /* turn on RTS */ 
rp->csr = CRS[dev].cr5 = CRS[dev].cr5 | RTS ; 
spix( priority ) ; 

} 


if( tp->t_iflag & IXOFF ) /* XON/XOFF stuff */ 


{ 
priority = spl4() ; 
if( tp->t_state & BUSY ) 
tp->t_state |= TTXON;/* send an XON during xmit interrupt */ 
else 


tp->t_state |= BUSY ;/* send an XON now */ 
rp->dbuf = nec_xon; 


} 
spix( priority ) ; 
} 
break ; 


DRIVERPROC(TP, T_SUSPEND-TP, T_RESUME) 


These routines are called to suspend and resume output. Their 
implementation is described in the main line of necproc. 


NOTE: The flag TTSTOP identifies this state. 
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This routine is called from the upper layers when a break is to be 
sent to the terminal for 1/4 second. Functions performed are: 


e Set hardware to send break. 
¢« Set the state to TIMEOUT. 


¢ Schedule a wakeup in 1/4 of a second to reset the hardware. — 


PNEC.BREAK.C LISTING 


* pnec.break.c -- T_BREAK routine. Called when a break is to 
* be sent to a terminal. 

* A break is sent for 1/4 of a second or HZ/4 ticks. 

* The routine ttrstrt will make the call necproc(tp, T_TIME) 


*/ 

priority = spl3() ; /* disable nec interrupts */ 
rp->csr = RP5 ; /* this is a hardware function */ 
rp->csr = CRS[dev].cr5 j= SEND BREAK ; 

sp1x( priority ) ; /* allow interrupts */ 
tp->t_state |= TIMEOUT ; /* timeout for 1/4 second */ 

timeout( ttrstrt, tp, HZ/4 ); /* then execute ttrstrt */ 
break ; 


DRIVERPROC(TP, T_TIME) 


A timeout has expired because the 1/4 second break transmission 
has completed. These functions are performed: 


e Clear the timeout flag in the state variable. 
e Reset the hardware to stop the transmission of the break. 


e Start the transmission of characters 
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PNEC.TIME.C LISTING 


* pnec.time.c -- T_TIME routine. Called when a timeout for 
* a terminal has expired. 

* The break will be turned off whether it was on or not. 

* control 4s transferred to start (see T_OUTPUT) to start the 
* transmission of characters. 


os 
tp->t_state &= “TIMEOUT; /* clear the timeout state */ 
switch( tp->t_cflag & CSIZE ) { /* reset break HW flag */ 
case CS5: /* this stuff is calculated because */ 
c = XCBITSS ; /* the same HW reg controls transmit bits */ 
break ; /* and break sending */ 
case CS6: 
c = XCBITS6 ; 
break ; 
case CS7: 
c = XCBITS7 ; 
break ; 
case CS8: 
c = XCBITS8 ; 
break ; 
} 
priority = sp13() ; /* disable interrupts */ 
rp->csr = RPS ; /* Don't turn off anything but break */ 
rp->csr = DTR | TRANS ENB {| RTS | c ; 
spix( priority ) ; /* enable interrupts */ 
goto start; /* start the transmission of characters */ 


PROC COMMAND - FLAG AFFECTED 


Figure 9.15 is a summary of the process commands and their 
influence on the related function. 
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Description 


T_BLOCK T_BLOCK !TTXON TTXOFF block input 

T_UNBLOCK 1T_BLOCK !TTXOFF TTXON start input 

T_SUSPEND TTSTOP stop output 

T_RESUME ITTSTOP start output 

T_OUTPUT none get t_buf, output char(s) 
T_BREAK TIMEOUT start break 

T_TIME 1 TIMEOUT stop break, output char(s) 
T_WFLUSH ITTSTOP reset t_buf, resume 
T_RFLUSH ITBLOCK ITTXOFF TTXON only if blocked 
T_LOG_FLUSH none input way to fast 

T_INPUT none none 

T_PARM none none 


T_SWTCH none none 


Figure 9.15. Process Commands 


CLOSE ROUTINE 


The close routine is used to call the LDR’s /_ close routine. If the 
DTR is to be turned off at close, the hardware must be informed. 


PNEC.CLOSE.C LISTING 

[Peccwccenecwccwwencwceccwnwcccwcwcccceccenswcccoceccccenccccocecececocece 

* pnec.close.c -- close routine 

Peccww ccc cwc ww wwe wwe ccwec ccc wccceccccccccewccccccoccccccccccccccccecece 

| 

necclose(minor_d, flag) 

devy_t minor_d; /* winor device number */ 

int flag; /* not used */ 

{ 
register struct tty *tp; /* pointer to tty for minor device */ 
register struct device *rp; /* register of device to close */ 
int priority ; /* original priority */ 


necsave ("necclose”); 


tp = &nec_tty[minor_d]; , /* tty pointer */ 
rp © nec_addr + minor_d ; /* register pointer */ 
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(*linesw[tp->t_line].1_close)(tp); | /* LOR close */ 
if ( minor_d = minor(consdev)) /* console is now closed */ 
console_open = FALSE ; 


priority = sp13() ; /* critical region */ 
rp->csr = RP3 ; 
rp->csr = RCBITS8 | AUTO_ENB; /* disable the receiver */ 
if ( tp->t_cflag & HUPCL && I(tp->t_state&ISOPEN) ) 
{ /* hang up on close */ 
rp->csr = RPS ; /* turn off DTR */ 


if (tp->t_cflag & PARENB) 

rp->csr = RTS | XCBITS7 | TRANS_ENB ; 
else 

rp->csr = RTS | XCBITS8 {| TRANS_ENB ; 


} 
spix( priority ) ; /* end critical region */ 


IOCTL ROUTINE 

The joct! routine calls the LDR /_ioci# procedure. The return value 
of the /_ioctl procedure tells whether the hardware configuration 
has been changed. If the hardware needs to be configured, then 
start the configuration from the beginning, using the bit flags in 
t_cflag. The hardware configuration is hardware dependent. 


ERROR HANDLING 


When errors are detected, the input bit flags t_iflag explain how 
errors are to be handled. 


INPCK Input parity check. If set, these types of error are 
handled: 


e Parity errors. 
« Framing errors that are not break characters. 


e Overrun errors. 
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IGNBRK Ignore break. A break causes a framing error. If a 
framing error occurs and the character read is 0377 
(all binary 1's), the driver should ignore the condition 
if this flag is set. If the flag isn’t set, this code should 
be executed: 


Signal(tp->t_pgrp, SIGINT); 
ttyflush(tp, (FREAD |FWRITE)); | 


PARMRK Parity framing and overrun errors should be marked 
with the three character sequence 


0377 0x 


NOTE: x is the character found to have a parity 
error. 


IGNPAR Ignore input errors. 
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INTRODUCTION TO DISK DRIVERS 


Disk device drivers control devices that permit random access of 
fixed size blocks. Blocks on the disk are numbered from zero to 
the size of the device minus one. The blocks are cached in the 
kernel for eventual reuse. Two interfaces are generally provided 
by a disk driver. A block device interface accessed through the 
Switch table bdevsw is the most frequently used interface. A 
character device interface accessed through the switch table 
cdevsw and is used for special purpose access. 


Block handling routines 


The Device Independent Kernel is a layer above the device driver 
(Figure 10.1). 


Device Independent Kernel 


Device Drivers 


Figure 10.1. Device Independent Layer 


UP-12230 R1 10-1 


Chapter 10 


The kernel has a layer of software, called the Block Handling 
routines, to increase the efficiency of handling disk devices. This 
modular design simplifies the integration of new disk drivers. This 
layer keeps a cache list of disk blocks in memory. Blocks to be 
read or written to disk pass through this cache. Commonly used 
blocks remain in the cache and are therefore accessed without the 
driver being invoked to physically retrieve the blocks. Caching is 
advantageous since the disk device is slow compared to 
processor speeds. The driver is concerned with efficient retrieval 
of disk blocks, not caching. 


Figure 10.2 shows the relationship between the device 
independent kernel, the block handling routines, and the device 
driver. 


Device Independent Kernel 


Block Handling 


Device Drivers 


Figure 10.2. Block Device Driver Layers 
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Buffers and Buffer Headers 


A reserved area of kernel memory is used for buffers to hold data 
to be written to the device or data that has been read from the 
device. Each kernel buffer is 1024 bytes long. 


When a process wants to copy a data structure to disk, it is 
actually copied to a kernel buffer at processor speeds and not 
immediately transferred to disk. When a block is requested, the 
system buffers (cache) are searched to see if the block is already 
in memory. If so, the system uses the block found in memory. If 
not, the block is read into a system buffer. This reduces |/O traffic 
since frequently used blocks stay in memory. 


This buffering also permits a process to handle any number of 
bytes at a time; the system buffers hold any unwanted data. For 
example, if a process writes ten bytes to a file on disk, the block 
that contains the ten bytes is read from disk into a kernel buffer. 
The ten bytes are then replaced with the user’s data. The kernel 
buffer is then put on the list of kernel buffers that needs to be 
written to disk at a later time. 


Each kernel buffer has a buffer header associated with it. The 
buffer header describes the transaction. Fields like device 
number, block number, kernel buffer pointer, etc. are contained in 
the buffer header. The buffer header also describes an operation 
that needs to be performed by a disk driver. The number of 
buffers and buffer headers is determined by the obuffer’s 
configuration parameter. 


Buffer Header Description 


The definition of a buffer header is found in the file 
/usr/include/sys/buf.h. Here is the buffer header structure 
definition from the file. 
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struct buf 
{ 
int b_flags; /* see defines below */ 
struct buf *b_forw; /* headed by d_tab of conf.c */ 
struct buf *b_back; feos *] 
struct buf *av_forw; /* position on free list, */ 
struct buf *av_back; {* if not BUSY*/ 
dev_tb_dev; /* major+minor device name */ 
int b_umd; /* unibus map descriptor */ 
unsigned b_bcount; /* transfer count */ 
union { 
caddr_t b_addr; /* low order core address */ 
int *b_words; /* words for clearing */ 


struct filsys *b_filsys; /* superblocks */ 
struct dinode *b_dino; /* ilist */ 
daddr_t *b_daddr; /* indirect block */ 

} b_un; 


fdefine paddr(X) (paddr_t)(X->b_un.b_addr) 


dadér_t b_bikno; /* block #@ on device */ 
char b_error; /* returned after 1/0 */ 
unsigned int b_resid; /* words not transferred after error */ 
time_t b_start; /* request start time */ 
struct proc ‘*b_proc; /* process doing physical or swap 1/0 */ 
struct buf *b_drsrbp; /* drs_stuff - bp of owning box */ 

}; 

/* 

* These flags are kept in b flags. 

* 


fdefine BLWRITE 0 /* non-read pseudo-flag */ 

fdefine B_READ 01 /* read when I/O occurs */ 

fdefine 8 DONE 62 /* transaction finished */ 

fdefine B_ERROR 04 /* transaction aborted */ 

fdefine 8 BUSY 010 /* not on av_forw/back list */ 

fdefine B_PHYS 020 /* Physical IO potentially using UNIBUS map */ 
fdefine B.MAPO4O /* This block has the UNIBUS map allocated sf 
define B WANTED 0100 /* issue wakeup when BUSY goes off */ 

fdefine  B_AGE0200 /* delayed write for correct aging */ 

fdefine B_ASYNC 0400 /* don't wait for 1/0 completion */ 

fdefine  B_DELWRI 01000 /* don't write till block leaves available list */ 
#define B_OPEN 02000 /* open routine called */ 

fdefine  B_STALE 04000 


fdefine B_DRSBITS Ox0f000000 = /* bits used by drs_code */ 


fdefine B_MASTER 0x08000000  /* B BUSY in home box drs_code i! 5 
_ fdefine DRS_BP_BITS 24 /* # of bits to sift to put in node # drs_code */ 
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The fields in the buffer header that relate to driver operation are: 


b flags 
Bit flags 


B ERROR 
Error during |/O operation 

B READ 
If set, the operation is a read; otherwise a write. 

B PHYS 
The operation is a direct transfer from user space to disk 
without passing through the block handling routines. 

av_forw 
Forward pointer on the device driver I/O queue. 

av_back 
Backward pointer if device driver I/O queue is doubly linked. 

b dev 
Major and minor device number of the device the block is 
found on. 

b _bcount 
Number of bytes to be transferred. This is typically 1024 
when the block handling routines are used. When the 
character device interface is used, this value could be any 
number. Normally only integral number of blocks are 
actually transferred. 

b_un 
Address of primary memory buffer to be transferred. When 
using the block handling routines, this is always a kernel 
buffer. 

b_blkno 
Block number on disk. The operating system assumes that 
all physical blocks are 512 bytes in length. 

6b error 
If the bit B_ERROR is set in b_flags, this error number is 
copied to the process's copy of the variable errno. 

b resid 
The number of bytes in the request that were not 
transferred. If, for example, 2048 bytes were requested and 
only 512 bytes were transferred, then the value of b_resid 
should be set to 1536. 
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b_proc 
Pointer to process table entry of the physical |/O process 
that requested the block. 


The fields in the buf structure are used by the block handling 
routines and can not be altered indiscriminately by the driver. 
Alterable fields of the buf structure are: 


b_flags 
The flag B_ERROR can be set. 
av_forw 
In complete control of the driver. 
av_back 
In complete control of the driver. 
b_error 
Error number returned to user program in variable errno. 
b_resid 
Number of bytes not transferred. 


Driver [/O Queue 


A driver I/O queue is an I/O request queue maintained by the 
driver. Buffer headers—associated with buffers waiting for the data 
to be read into them, or buffers waiting for the data to be written 
back to disk—are linked onto this queue. The jobuf structure is an 
anchor for this queue and contains two fields used for list 
manipulation: 


b_acttf 

Pointer to the beginning of the driver I/O queue 
b acti 

Pointer to the end of the driver I/O queue 


Figure 10.3 provides a representation of a doubly linked driver I/O 
queue. 


10-6 UP-12230 R1 


A Virtual Disk Driver 


w7-~ 1obuf structure Buffer Headers 


av__forw av__forw 


| av_back (| av_ back |_| 


av__forw 
av__ back 


Figure 10.3 Driver 1/0 Queue 


The driver I/O queue is only used by the driver, so a singly linked 
list could be used. Typically, there is a driver I/O queue for each 
device controlled by the driver. 


Block Device interface 


The block device interface is used for communication between the 
block handling routines and the device driver. The device driver is 
responsible for 512-byte physical blocks of data. The block 
handling routines generally request these physical blocks two at a 
time. Most disk devices can be requested to transfer both of the 
physical blocks in one operation. During initialization, when the 
boot block and super block are read, only one physical block is 
requested. 


Bdevsw 


The block device driver is called using the bdevsw table. The 
similarities between cdevsw and bdevsw are apparent. The driver 
is identified by its major device number. Bdevsw is described in 
/usr/include/sys/cont.h: 


/* 
* Declaration of block device switch. Each entry (row) is 
* the only link between the main unix code and the driver. 
* The initialization of the device switches is in the file conf.c. 
*/ : 
struct bdevsw { 
int (*d_open)(); 
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int (*d_close)(); 
int (*d_strategy)(); 
int (*d_print)(); 

}; 


extern struct bdevsw bdevsw[); 


There are a few differences between the bdevsw and cdevsw 
tables. There is no d_ioct! routine in the bdevsw table. The 
routine d_strategy replaces the d_read and the d_write routines. 
The d_print routine is maintained for historical compatibility and is 
generally not used. 


VIRTUAL DISK DRIVER DESCRIPTION 


The virtual disk driver (vo) allocates an array of 512 byte blocks 
that can be used to store data. The following C statements 
describe the driver's disk storage: 


#define VDPBLK 0x200 /* physical block size in bytes */ 
fdefine VDPBLKS 0x100 /* number of physical blocks on disk */ 
struct vdblock 

{ . 

char data [VDPBLK]; 


} 
struct vdblock vddisk[VDPBLKS]; 
The address of block b in the disk is described with this C 
statement: 


char * block_addr; 
block addr = &vddisk[b]; 


Vdopen Definition 


The vdopen routine is called using the bdevsw table. The minor 
device is validated. For a flex disk, the read/write notch on the flex 
could be sensed. On a hard disk, the existence of the disk could 
be verified. 
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Vdopen listing 
[Sscemeneeietisd nip ccnaecenanetseunnientaduckuaweednene Uesivedduneoudexcess 
* vdopen - open call common for block and character device interface 
Wewmmewewwcwwow eww wccewwww cece ccc ccccen ence ccccccuccccccccccccecccucecce 
vdopen(minor_d, flags) 
dev tminor_d; /* minor device number */ 
int flags; /* flags are ignored */ 
{ 
printl("vdopen\n"); 
if (minor_d >= vd_cnt) /* minor device does not exist */ 
u.u_error = ENXIO; 
} 


Virtual Driver Strategy Definition 


The strategy routine performs both read and writes from the disk. 
A buffer header that fully describes the operation is passed as a 
parameter. When controlling a “real” device, the buffer header is 
put on the driver I/O queue, after which control is passed back to 
the block handling routines. It’s up to the ISR to signal completion 
of the operation by calling iodone(k). Vd has no ISR, so the 
operation is completed immediately and jiodone is called. The 
buffer header is first verified to be correct. If the requested block 
is one block beyond the end of the device, an end-of-file condition 
exists which is not considered an error. If other blocks beyond the 
last block have been requested, an error condition exists. 


The routine b/t(k) is a fast way to copy buffers. Blt doesn't do error 
checking so it should not be used for copying data into and out of 
user space. lodone(k) is called to signal the upper layers that the 
operation described by the buffer header has been completed. 
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Vdstrategy listing 


*/ 
vdstrategy(bp) 
struct buf *bp; 


{ 
int physblk; 


if (vdverify(bp)) 


vdrequest(bp); 
{odone(bp); 
} 
[tewccceennenn nen en ewww nnn ene nnnroeneeneenenenenenncconncnnncccsercnenecas 


* vdverify - verify buffer pointer, return true to continue with the 
* request or false to stop processing 


*/ 

vdverify (bp) 

struct buf * bp; 

{ 

if (bp->b_bikno == VDPBLKS) /* end of file, not really an error */ 
{ 
bp->b_resid = bp->b_bcount; /* number of bytes not yet transfered */ 
return FALSE; 


} 
else if (bp->b_blkno > VDPBLKS) /* error: block number 1s to hi */ 
{ 
printl("error block number to high\n"); 
bp->b_resid = bp->b_bcount; /* number of bytes not yet transfered */ 
bp->b_flags j= B_ERROR; 
return FALSE; 
} 
else 
return TRUE; 


a J 
vdrequest(bp) 
struct buf * bp; 


print2("buffered %x\n", bp->b_bIkno); 
if (bp->b_flags & BREAD) /* read or write operation */ 
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bit (bp->b_un.b_addr, &vddisk[bp->b_blkno], bp->b_bcount); 
else 
bit (&vddisk(bp->b_bikno], bp->b_un.b_addr, bp->b_bcount); 


Virtual Disk Driver Complete listing 


al 

finclude <sys/sysmacros.h> 
#include <sys/types.h> 
#include <sys/param. h> 
#include <sys/signal.h> 
#include <sys/errno.h> 
#include <sys/dir.h> 
#finclude <sys/file.h> 
#include <sys/user.h> 
#include <sys/buf.h> 
#include <sys/fobuf.h> 
#include <sys/b0.h> 
#include <sys/proc. h> 


[lodesetecctwchédinenbancubuas tedeedebuccwaensadwotceubeddauseacucke 
* global definitions 

Di eSR SONS eK eee deSeeeDnerenesdnscsedctusceceasacweeeesseseceedcucoeus 
*f 

fdefine | VDPBLK 0x200 /* physical block size in bytes */ 


#define  VDPBLKMSB Oxfffffe00 /* physical block most sig bit mask */ 
#define VDPBLKLSB Oxi ff /* physical block least sig bit mask */ 
#define VDPBLKSHIFT 0x09 /* power of 2 equal to VDPBLK */ 

#define | VOPBLKS 0x100 /* number of physical blocks on disk */ 


struct vdblock 


{ 
char data[VDPBLK]; 


}i 
struct vdblock vddisk[VDPBLKS]; - 


struct buf vd_buf; /* internal buffer */ 
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* debugging routines 
# coc ececneeeeoeeweccoe weer ecceceewecesewessew roscoe ssocecoeeeosoeesoseceses 
*/ 
#def ine DEBUG ~ 
#ifdef DEBUG 
int vd_debug = 1; 
# define printl(a) vd_printf(a) 
2 define print2(a,b) vd_printf(a,b) 
# define print3(a,b,c) vd_printf(a,b,c) 
# define print4(a,b,c,d) vd_printf(a,b,c,d) 
a define print5(a,b,c,d,e) vd_printf(a,b,c,d,e) 
vd_printf(a,b,c,d,e) 
{ 
if (vd_debug) printf(a,b,c,d,e); 
} 
felse 


define printl(a) 
# define print2(a,b) 
£ define print3(a,b,c) 
# define print4(a,b,c,d) 
# define print5(a,b,c,d,e) 
#endif 


*/ 
extern int vd_cnt; /* number of minor devices */ 


#define TRUE 1 
#define FALSE 0 


[tanccecwnnnnnnnnnn www nnen enn nnn n nnn nn nnn nn nnnn nnn nnn nnnnnn enn e nnn ennnne= 
* ydopen - open call common for block and character device interface 
* i cwmowceseceweeeeweeewewwoewceweoooeor soc oecocoe coco esocoecoooooososooecss 
a 
vdopen(minor_d, flags) 
dev_tminor_d; /* minor device number */ 
int flags; /* flags are ignored */ 
{ 
printl("vdopen\n"); | 
if (minor_d >= vd_cnt) /* minor device does not exist */ 
u.u_error = ENXIO; Y. 
} 
[Bannnencn nnn nnnnnnnnnnn nnn n nnn n nnn e ene nen e nnn nnn enn e mene nen eneeneeceweee 
* ydstrategy - strategy routine 
© ome ewmecenewoeeenc enn eee ean cce re cn cee ee cece eee cases eee case esonsesoce 
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*/ 
vdstrategy(bp) 
struct buf *bp; 


{ 
int physblk; 


if (vdverify(bp)) 


vdrequest(bp); 
fodone(bp); 
} 
[tocecenennnn nnn nn nn nnn nnn n nn nnn nnn nn nn neeee ene e new e een e wenn nee eeneccoenee 


* ydverify - verify buffer pointer, return true to continue with the 
* request or false to stop processing 


a} 
vdverify (bp) 
struct buf * bp; 


{ 
if (bp->b_blkno == VDPBLKS) /* end of file, not really an error */ 
{ 
bp->b_resid = bp->b_bcount; /* number of bytes not yet transfered */ 
return FALSE; 
} 
else if (bp->b_bikno > VDPBLKS) /* error: block number is to hi */ 
{ 
printl(“error block number to high\n"); 
bp->b_resid = bp->b_bcount; /* number of bytes not yet transfered */ 
bp->b_flags {= B_ERROR; 
return FALSE; 


} 
else 
return TRUE; 
} 
[Bocccccnceeccnnneenn enn nee ee enn n ewe een wenn enne enon ennen ne ecenceenenenes 
* ydrequest - fullfill a request 
® rceccew ccc cece cc cc ew cee eo ce ccwcce cc wc cecceowes ees eweseccceecseseoserre 
*/ 
vdrequest(bp) 
struct buf * bp; 
{ 
print2("buffered %x\n", bp->b_blkno); 
if (bp->b flags & BREAD) /* read or write operation + 
bit (bp->b_un.b_ addr, &vddisk[bp->b_bikno], bp->b_bcount); 
else 
bit (&vddisk[bp->b_blkno], bp->b_un.b_addr, bp->b_bcount); 
} 
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vdelose() 


{ 
printl("vdclose: not imp lemented\n”); 


*/ 
vdprint() 


{ 
printl("vdprint: not implemented\n"); 


i | 
vdioct1() 


{ 
printl("vdioct]: not implemented\n"); 
} 


CHARACTER DEVICE PORTION OF THE DRIVER 


A character device interface is also provided by disk drivers. This 
interface is defined in exactly the same way as any other character 
device. The character device portion for a disk driver has the 
following unique characteristics. 


An ioctl call is provided as a way to format the disk, define 
disk characteristics like number of sectors read, and to set 
the bad block table, etc. 


A read and write system call requires that the driver transfer 
data directly from user buffers to disk blocks without using 
the kernel buffers. A special kernel call, physio(k), helps 
perform this task. 
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This interface is sometimes called the "physical" device interface. 
From the process’s point of view, data is moved directly between a 
physical device and process memory (no kernel buffers). This is 
known as Raw I/O. The read and the write routines aren't 
important and are described in the following example. 


Character Read and Write Listing 


struct buf vd_buf; 


*/ 
vdread(minor_d) 
dev_t minor_d; 


{ 
physio(vdstrategy, &vd_buf, minor_d, B_READ); 


*} 
vdwrite(minor_d) 
dev_t minor_d; 


{ 
physto(vdstrategy, &vd_buf, minor_d, B_WRITE); 


} 


PHYSIO I/O 
The physio call is: 


physio(strategy, bp, minor_d, flag) 


int (strategy *)(); /* drivers strategy routine */ 
struct buf * bp; /* buffer header */ 

dev_t minor_d; /* minor device number */ 

int flag; /* 0 - Write 1 - Read */ 


The buffer pointer provided is filled with values from the user 
structure and the parameters. The driver's strategy routine is then 
called to perform the operation. Paging systems break one large 
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operation into 64K pieces and call the driver's strategy routine. 
Swapping systems call the strategy routine only once. The portion 
of the process required for the I/O operation is also mapped and 
locked into memory by physio. 


Physical I/O Strategy Definition 


The strategy routine for the virtual disk driver works correctly with 
no changes. The bit call, however, does no error checking and 
could cause disastrous results. It has therefore been replaced by 
copyin(k) and Icopyout(k) that do error checking. 


Physical 1/O Strategy Listing 


vdstrategy(bp) 
struct buf *bp; 


{ 
int physblk; 


if (vdverify(bp)) 


vdrequest(bp); 
jodone(bp); 
} 
[Bannnnn nnn nnn nnn nnn nnn wn nnn nnn nnn een ee nen e een e nen nnnneennneeemeeennnenee 


* vdverify - verify buffer pointer, return true to continue with the 
* request or false to stop processing 


vdverify (bp) 
struct buf * bp; 
{ 
if (bp->b_blkno == VDPBLKS) /* end of file, not really an error */ 
{ 
bp->b_resid = bp->b_bcount; /* number of bytes not yet transferred */ 
return FALSE; 
} 
else if (bp->b_blkno > VOPBLKS) /* error: block number {s too high */ 
{ 
printl("error block number too high\n"); 
bp->b_resid = bp->b_bcount; /* number of bytes not yet transferred “7 
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bp->b_flags j= B_ERROR; 
return FALSE; 


} 
else 
return TRUE; 
} 
]¥ cuits ckteice euan Rie ae eUNAR NRE eRe Naudia Keianmene eden 
* vdrequest - fullfill a request 
Wi taba wbew eee bbweceecacdataudeeadtdince cactdticuwdcuusecedeceSesws 
=] 
vdrequest(bp) 
struct buf * bp; 
{ 
if (bp->b_flags & B PHYS) /* physio call */ 
{ 
print2("physio %x\n", bp->b_b1k\n"); 
if (bp->b_flags & B READ) /* read or write operation */ 
copyout (&vddisk[bp->b_blkno], bp->b_un.b_addr, bp->b_bcount); 
else 
copyin (bp->b_un.b_addr, &vddisk[bp->b_blkno], bp->b_bcount); 
} 
else /* normal buffered io call */ 
sf 
print2("buffered %x\n", bp->b_bik\n"); 
if (bp->b_flags & BREAD) /* read or write operation */ 
bit (bp->b_un.b_addr, &vddisk[bp->b_blkno], bp->b_bcount); 
else 
bit (&vddisk[bp->b_blkno], bp->b_un.b_addr, bp->b_bcount); 
} 
} 


MEMORY MANAGEMENT AND DISK DRIVERS 


Typically, because the kernel handles memory mapping, the 
device driver writer does not need to be concerned with the 
logical functions of MMU. However, for Raw I/O, a disk driver may 
need to map the DMA context in order to transfer data to user 
memory. This MMU overview provides some insight as to the use 
of and functions of the MMU as it relates to address translation. 
The following section in this chapter provides specific information 
relating to the driver and MMU and extends the disk driver 
example to include MMU mapping concepts. Also, the Tuning 
Guide is an_ excellent source for information relating to 
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driver/kernel memory management parameters. 


Memory Management Overview 


The function of the memory management unit is to take logical 
addresses provided by the CPU and convert those addresses into 
physical addresses of memory bytes. Figure 10.4 provides a 
simplified diagram of memory management. 
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Figure 10.4. Memory Management Translation Overview 
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Figure 10.5. Memory Management Contexts 
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Primary MMU Elements 


The three primary MMU elements are (Refer to Figure 10.4): 
Context Register 
Segment Map 
Page Map 


the contents of the three elements control the logical address to 
physical address translation function. 


Address Translation 


Logical to physical address translation takes place through the 
current context, selected by the context register, and by dividing 
the logical address into three parts. These three parts are the 
segment register index, the page index, and the page offset. 


Context Register 


The context register points to the current context in the segment 
map. 


Having more than one context permits many processes to be 
loaded into the MMU and context switching to be done by simply 
changing the value in the context register. The last context in the 
segment map is reserved for use by DMA devices. All DMA 
memory access automatically forces the segment map to the DMA 
context for the duration of the transfer. This is enforced by the 
hardware and cannot be changed. 
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Segment Register Index 


The segment register index selects a segment register from the 
current segment map. The segment register contains protection 
bits and a page block number. The protection bits are used to 
make certain that the process that generated the logical address is 
permitted to access the physical memory. The page block number 
points to a block of 16 page registers. 


Page Register Index 


The next step in address translation involves the page index. 
From the logical address, the page register index selects one of 
the 16-page registers, in the page map, from the page block 
specified by the segment register. The page register contains the 
memory space bits and the physical page address. The memory 
space bits specify that the physical memory is: invalid, local 
system memory, multibus memory, or multibus I/O. The physical 
page address is shifted left 11 bits and becomes the most 
significant bits of the physical address. 


Up to this point the MMU has not been an issue because all of 
kernel space is mapped identically into all contexts. 


When the device being controlled transfers information into kernel 
space-for example, into the kernel buffers— it doesn’t matter how 
the non-kernel segments in the DMA context are filled since they 
are never used. If, however, a user buffer is to be accessed in the 
DMA context, the buffer must be mapped into the user space of 
the DMA context before DMA begins. 


The virtual disk driver doesn’t have a problem since it does not 
actually use DMA and therefore doesn’t use the DMA context. A 
device driver, however, can temporarily execute code in the DMA 
context. This permits the simulation of DMA and demonstrates 
memory mapping concepts by extending the virtual disk driver 
example. 
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Figure 10.6. Memory Management Mapping 
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Mapping User Space Into The DMA Context 


NOTE: The 5000/55 MMU is used for the examples in the ww 
remaining sections of this chapter. The DMA context for this 
MMU is Context 31. 


In order to map user space into the DMA context (refer to Figure 
10.6), the following steps are taken: 


Segments need to be reserved for use in context 31 for 
mapping of user space. 


A page block needs to be allocated for use by the driver. 


Each time physical I/O takes place, the correct physical 
addresses of user space must be initialized to map user 
space. Requests may need to be broken into smaller chunks 
if they are larger than the map space. 


Segment Allocation 


Segment allocation is part of the kernel configuration process. 
The bit called "required DMA resources" in the master file entry for 
the driver must be set. The config variable dmanpb is the number 
of page blocks and segments needed for each driver that requires 
DMA resources. The value of dmanpb is normally two. The 
external variable <hp>npb has the number of DMA segments 
assigned to the driver. The external variable <hp>/seg is the 
logical address that identifies the segment reserved for the driver. 


Reserving Page Blocks 


Once, at system initialization, the page blocks needed by the 
driver are reserved. Dmamalloc(k) is used to reserve the page 


blocks. ) 
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NOTE: The number of bytes needed to map, not the 
number of page blocks needed, is the parameter for this 
routine. 


Mapping User Space 

Mapping user space into context 31 updates the MMU so that 
physical addresses corresponding to a user buffer can be 
accessed using logical addresses in context 31. 


The kermel function call dmapit(k) brings together the following 
parameters to initialize the MMU. 


Logical address space (segments) allocated during 

configuration (<up>lseg). 

Pages allocated by dmamalloc 

Physical addresses of user space to be mapped. 
Accessing logical addresses, starting at address <hp>/lseg in 
context 31, addresses the same clicks in physical memory of the 
user buffer. The process of breaking up a large user buffer into 


smaller buffers and mapping those buffers interactively into context 
31 is not a trivial process. 


Virtual Disk Driver Init Definition 
The initialization routine was added to reserve the page blocks 


needed. There are 32k bytes per page block. The value of vdnpb 
was two; a total of 64k bytes were requested. 
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* ydinit - initialize routine. Allocate page blocks from the page map 


“| 
vdinit() 


{ 

vdpages = dmamalloc(VDMAPBYTES); 

printl("vdpages: %x, vdnpb: %x, vdlseg: %x\n", vdpages, vdnpb, vdlseg); 
} 


Strategy Definition 


A new strategy routine specifically for physical I/O has been 
added. This routine has all of the intelligence needed to map the 
[/O request into the DMA context and to start the DMA transfer. 


The user buffer is broken up into smaller pieces. DMA is then 
performed on each piece. Figure 10.7 shows the user buffer and 
the DMA context DMA map buffer starting at the address vol/seg 
and continuing for 64k bytes. The user buffer must be broken into 
pieces with these characteristics: 


An even number of physical disk blocks must be contained in 
the buffer. 


The maximum amount of space should be mapped. 
The DMA buffer size of 64k cannot be exceeded. 


In the example, the number of mappable blocks in the user buffer 
can be calculated by: 


(64k - clkoffset)/512 


The number of bytes between the user buffer and the next lower 
click boundary is the value of clkoffset. In other words, the 
maximum number of bytes that could be mapped is 64k (128 
blocks) if the user buffer happened to begin on a click boundary. 
lf the user buffer doesn’t begin on a click boundary, the number of 
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bytes specified by clkoffset and the number of bytes in the partial 
block at the end of the map buffer are wasted (Figure 10.8). The 
following C code initializes variables used to define the buffer. 
Usrbuf is the user buffer to transfer, bikno is the block number on 
disk, and bo->b_resid is the number of bytes left to transfer. 


usrbuf = bp->b_un.b_addr; /* user buffer */ 
bikno = bp->b_bikno; /* starting block number on disk */ 
bp->b_resid = bp->b_bcount; /* number of bytes to transfer total */ 


The following code is the C source that performs the mapping 
calculations. 


clkoffset = (int)usrbuf & CLKLSB; /* offset into first click */ 


/* byte count */ 
bcount = min((VOMAPBYTES - clkoffset), bp->b_resid) & VDPBLKMSB; 
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Figure 10.7. DMA/Buffer Map 
VDMAPBYTES is 64K. The DMA map area can be mapped using 
these variables: 
dmapit(vdiseg, vdpages, usrbuf, bcount, bp->b_proc->p_spt); 
The function call dmapit performs these functions: 


e The segment map in context 31 is initialized to the page 
blocks indicated by vopages. 


e The page map is filled with the click addresses identified by 
usrbuf, bcount and bp->b_proc->p_ spt. 
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Figure 10.8. First Map 


After this call has completed, the data in the first piece of the user 
buffer can also be accessed in context 31 by using addresses 
starting at volseg. The buffers and counters are all incremented 
and the process is repeated. 


Figures 10.9 and 10.10 show the second and last maps. 
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Figure 10.10, Last Map 


PHYSICAL DEVICE IMPLEMENTATION 


The following sections provide the code for the physical device 
implementation. 


Read 


*/ 
#define CLKLSB Ox7ff /* click least significant bits */ 
#define CLKMSB Oxfffff800 /* biick most significant bits */ 
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* external references 


ui 
extern int vd_cnt; /* number of sub devices */ 
extern short vdnpb; /* number of 32k dma segments reserved */ a, 


extern char * vdlseg; /* address of first dma segment in context 31 */ 


define VDMAPBYTES (vdnpb * 0x8000) /* number of bytes in the dma map area */ 


int vdpages; /* page block pointer filled in vdinit */ 
[tocwceennnncncennne wenn conn nn nen erence re cencnnecnwewocewconwowoscooonoce 
* vdpstrat - physical fo strategy using dma techniques 
Ceo ccccc weer ce cwccwcccoeceroocecccocceecoeccesses weececcecececcnsceecosceccco 
“/ 
vdpstrat(bp) 
struct buf * bp;/* buffer pointer describing physical fo */ 
{ 
int clkoffset; /* bytes at begining of first click that are skipped */ 
int bikno; /* current block number */ 
int bcount; /* number of bytes to transfer */ 
char * mapbuf; /* buffer mapped in context 31 */ 
char * usrbuf; /* buffer in user space */ 
printf("vdpstrat: "); N ] 
if (vdverify(bp)) 
{ 
usrbuf = bp->b_un.b_addr; /* user buffer */ 
bikno = bp->b_bikno; /* starting block number on disk */ 


bp->b_resid = bp->b_bcount; /* number of bytes to transfer total */ 
while (bp->b_resid >= VDPBLK && bikno < VOPBLKS ) 


{ 

clkoffset = (int)usrbuf & CLKLSB; /* offset into first click */ 
/* byte count */ 

bcount = min((VDMAPBYTES - clkoffset), bp->b_resid) & VDPBLKMSB; 

dmapit(vdlseg, vdpages, usrbuf, bcount, bp->b_proc->p_spt); 

mapbuf = (char *)((int) vdlseg | clkoffset); /* offset into dma map */ 

startdma(mapbuf, bikno, beount, bp->b_flags); 

bikno += bcount >> VDPBLKSHIFT; /* bcount div 512 */ 

bp->b_resid -= bcount; 

usrbuf += bcount; 

} 


} 
jodone(bp); 
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vdcallrequest (bp _p) 

struct buf ** bp p; 

{ 

print2("vdcallrequest: *bp_p->b_un.b_addr %x\n", (*bp_p)->b_un.b_addr); 
vdrequest(*bp_p); 

} 


startdma(mapbuf, blkno, bcount, flags) 
char * mapbuf; 

int bikno; 

int bcount; 

int flags; 


4 
struct buf tempbuf; 


print5("startdma: mapbuf: %x, blkno: %x, bcount: %x, flags: %x\n", mapbuf, bikno, bcount, flags); 


tempbuf.b_un.b addr = mapbuf; 
tempbuf.b flags = flags; 
tempbuf.b_bikno = bikno; 
tempbuf.b_bcount = bcount; 
cntxt31(vdeallrequest, &tempbuf); 


} 


struct buf vd_buf; 


*/ 
vdread(minor_d) 
dev_t minor_d; 


{ 
physio(vdpstrat, &vd_buf, minor_d, 8 READ); 


* 

vdwrite(minor_d) 

dev_t winor_d; 

{ 

physio(vdpstrat, &vd_buf, minor_d, 8 WRITE); 


} 


UP-12230 R1 10-33 


Chapter 10 


aE REN NR RISES ESP OO AO 


Complete Block and Physical Device Driver 


"y 

#include <sys/sysmacros.h> 
finclude <sys/types.h> 
finclude <sys/param. h> 
finclude <sys/signal.h> 
finclude <sys/errno.h> 
finclude <sys/dir.h> 
finclude <sys/file.h> 
#include <sys/user.h> 
finclude <sys/buf.h> 
#include <sys/tobuf.h> 
#include <sys/b0.h> 
#include <sys/proc.h> 


[taccocceonccconeenecersceocorersorenecsorerccococoonnozcnconscosanene 

* global definitions 

® cecceccccccecwwwecc cen cenccewceccceeresorsccesecceocnsecoeosossesee 

*/ 

fdefine  VOPBLK 0x200 /* physical block size in bytes */ 


fdefine | VOPBLKMSB Oxfffffe0d /* physical block most sig bit mask */ 
#define VDPBLKLSB Oxiff /* physical block least sig bit mask */ 
fdefine VDPBLKSHIFT 0x09 /* power of 2 equal to VOPBLK */ 

fdefine | VDPBLKS 0x100 /* number of physical blocks on disk */ 


struct vdb lock 
{ 
char data{VDPBLK); 
}: 
struct vdblock vddisk[VDPBLKS]; 


struct buf vd_buf; /* internal buffer */ 


[teenece wcceweccecceccwcecccc ew ewcccccceccenccccceseesaseccoscooscoscesece 
* debugging routines 


a 
fdef ine DEBUG 
#ifdef DEBUG 
int vd_debug = 1; 
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define printl(a) vd_printf(a) 
define print2(a,b) vd_printf(a,b) 
define print3(a,b,c) vd_printf(a,b,c) 
define print4(a,b,c,d) vd_printf(a,b,c,d) 
define print5(a,b,c,d,e) vd_printf(a,b,c,d,e) 
vd_printf(a,b,c,d,e) 

{ 

if (vd_debug) printf(a,b,c,d,e); 

} 


es & & Gh 


felse 

# define printl(a) 

# define print2(a,b) 

# define print3(a,b,c) 

3 define print4(a,b,c,d) 

# define print5(a,b,c,d,e) 
fendif 


a | 
extern int vd_cnt; /* number of minor devices */ 


#define TRUE 1 
#define FALSE 0 


“} 
vdstrategy(bp) 
struct buf “bp; 


{ 
int physb lk; 


if (vdverify(bp)) 


vdrequest(bp); 
jodone(bp); 
} 
| OE 


* vdverify - verify buffer pointer, return true to continue with the 
* request or false to stop processing 


a 
vdverify (bp) 
struct buf * bp; 


{ 
if (bp->b_bIkno == VOPBLKS) /* end of file, not really an error */ 


{ 


UP-12230 R1 7 10-35 


Chapter 10 


Le TT LI ET 


bp->b_resid = bp->b_bcount; /* number of bytes not yet transfered */ 
return FALSE; 
} 
else if (bp->b_blkno > VDPBLKS) /* error: block number 1s to hi */ 
{ 
printl("error block number to high\n"); 
bp->b_resid = bp->b_bcount; /* number of bytes not yet transfered */ 
bp->b_flags {= B_ERROR; 
return FALSE; 


} 
else 
return TRUE; 
} 
[tenccccennnceccoeren mene een n nn nnerennnennn mene nn wonencncocccscccorcrecons 
* vdrequest - fullfill a request 
© ccc ccc ccc cc wee wewwcw were eres e coon cow ceene ess ccccsrocosconesesesesccone 
*} 
vdrequest(bp) 
struct buf * bp; 
{ 
{f (bp->b_flags & B_PHYS) /* physio call */ 
print2("physio %x\n", bp->b_bikno); 
if (bp->b_flags & B_READ) /* read or write operation */ 
copyout (&vddisk[bp->b_blkno], bp->b_un.b_addr, bp->b_bcount); 
else 
copyin (bp->b_un.b_addr, &vddisk[bp->b_bikno], bp->b_bcount); 
} 
else /* normal buffered {o call */ 
{ 
print2("buffered %x\n", bp->b_bikno); 
if (bp->b_flags & BREAD) /* read or write operation */ 
bit (bp->b_un.b addr, &vddisk[bp->b_blkno}, bp->b_bcount); 
else 
bit (&vddisk(bp->b_blkno], bp->b_un.b_addr, bp->b_bcount); 
} 
} 
/* meee ccc ccc cc eee ccee cco ccccc cc ece econ ecco ceccocoowcessosconseweseneenee 
* ww constants 
Bi cnccccccccccc cece ccm ecco wnewcwcccewcccecccccocceccceosecesocosooncccce 
*/ 
#define CLKLSB Ox7ff /* click least significant bits */ 


#define CLKMSB Oxfffff800 /* blick most significant bits */ 
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extern int vd_cnt; /* number of sub devices */ 

extern short vdnpb; /* number of 32k dma segments reserved */ 

extern char * vdiseg; /* address of first dma segment in context 3] */ 
#define VOMAPBYTES (vdnpb * 0x8000) /* number of bytes in the dma map area */ 
int vdpages; /* page block pointer filled in vdinit */ 


|Bacncdatcwosevewnsueiasecuss seveeueauune deviendeesgeeucuancebansawasnennn 


* vdpstrat - physical jo strategy using dma techniques 


*] 

vdpstrat(bp) 

struct buf * bp;/* buffer pointer describing physical io */ 

{ 

int clkoffset; /* bytes at begining of first click that are skipped */ 
int bikno; /* current block number */ 

int bcount; /* number of bytes to transfer */ 

char * mapbuf; /* buffer mapped in context 31 */ 

char * usrbuf; /* buffer in user space */ 


printf("vdpstrat: "); 
if (vdverify(bp)) 


{ 
usrbuf = bp->b_un.b_addr; /* user buffer */ 
bikno = bp->b_bikno; /* starting block number on disk */ 


bp->b_resid = bp->b_bcount; /* number of bytes to transfer total */ 
while (bp->b_resid >= VDPBLK && bikno < VOPBLKS) 
{ 
clkoffset = (int)usrbuf & CLKLSB; /* offset into first click */ 
/* byte count */ 
bcount = min((VDMAPBYTES - clkoffset), bp->b_resid) & VDPBLKMSB; 
dmapit(vdiseg, vdpages, usrbuf, bcount, bp->b_proc->p_spt); 
mapbuf = (char *)((int) vdlseg | clkoffset); /* offset into dma map */ 
startdma(mapbuf, bikno, bcount, bp->b_flags); 
bikno += bcount >> VDPBLKSHIFT; /* bcount div 512 */ 
bp->b_resid -= bcount; 
usrbuf += bcount; 


} 
} 
{odone(bp); 
} 
[tewccece crew enn new n nee new w enon ence new e ene woe ewe neencen enw eweneneceeeceee 


*/ 
vdcallrequest (bp_p) 
struct buf ** bp_p; 


{ 
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print2("vdcallrequest: *bp_p->b_un.b_addr %x\n", (*bp_p)->b_un.b_addr); 
vdrequest(*bp_p); 
} 


startdma(mapbuf, blkno, bcount, flags) 
char * mapbuf; 

int blkno; 

int bcount; 

int flags; 


{ 
struct buf tempbuf; 


print5("startdma: mapbuf: %x, blkno: %x, bcount: %x, flags: x\n", mapbuf, blkno, bcount, flags); 


tempbuf.b_un.b_addr = mapbuf; 
tempbuf.b flags = flags; 
tempbuf.b_bikno = bikno; 
tempbuf.b_bcount = bcount; 
cntxt31(vdcallrequest, &tempbuf); 


} 


struct buf vd_buf; 


[Beeeewen ec wec ween ween nen wen wenn cwen nnn wnenneen nnn ewewnennnewereocncnwore 
* ydread - character device interface read routine 

Br ccwwccer ecco weccceccceccccwewccwwo cone corercces corer cence sccseseseoore 
*/ 

vdread(minor_d) 

dev_t minor_d; 

{ 

physio(vdpstrat, &vd_buf, minor_d, B_READ); 

} 

/* ee ed 
* vdwrite - character device interface write routine 

bo wcce crew cee fO Cee eee ee 0 0906 00088808 FOSS S8SSST SSS SESS SSOSSHVOSESSSSOOSE 
a 

vdwrite(minor_d) 

dev_t minor_d; 

{ 

physio(vdpstrat, &vd_buf, minor_d, B_WRITE); 

} 

/* come eee ce cece cece ecw c ccc n cee cwweneeeonccccoececeweew eee soseneeeesocns wae 
* ydinit - initialize routine. Allocate page blocks from the page map 

Rr cccc ccc ccc ee cce cece ee eweccecec csc ee cocceneccesnsosssssesesussoesesaeoas 
a 

vdinit() 

{ 


vdpages = dmama 1 loc(VDMAPBYTES); 
print] ("vdpages: %x, vdnpb: %x, vdlseg: %x\n", vdpages, vdnpb, vdiseg): 
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vdc lose() 


{ 
printl("vdclose: not implemented\n"); 


vdprint() 


{ 
printl("vdprint: not implemented\n"); 


vdioct1() 


{ 
printl("vdioctl: not implemented\n"); 


} 
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POWER FAIL RECOVERY 


When the power supply hardware detects a power failure, a power 
down interrupt is issued to inform the kernel. After the power 
down interrupt is issued, the kernel has a short amount of time to 
save the system registers and the contents of the time of day chip. 


The return of external power initiates the following sequence of 
events: 


¢ The kernel restores the memory management unit. 

¢ The kernel forces a level 1 interrupt to be pending. 

¢ This return to the point where the power failure occurred 
permits any critical code segments, which were interrupt by 
power down, to complete. 

e The level 1 interrupt occurs and returns control to the kernel. 

« The kernel enables the critical out routines. 


e The kernel calls the driver power clear routines. 


e After the last power clear routine has returned, the kernel 
returns from the level 1 interrupt and execution resumes. 


Returning to the point of the down interrupt is done to permit any 
driver or kernel critical code segment to complete before the 
drivers are called to perform their power fail recovery tasks. For 
example, consider the case where power down occurs in a disk 
driver's queuing routine. If this code is not permitted to run to 
completion, the state of the driver's queues is not known. If the 
driver's power clear routine manipulated these queues, they would 
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become even more confused. 
Critical segments must be protected by priority level of 1 or higher. 


The critical out routines (coutb, coutw, coutl) are used by drivers to 
access on-board registers. Calls to the routines have the form: 


coutx (register_addr, data); 


Where x is: 
b - If data is a byte. 
w - If data is a word (16 bits). 
| - If data is a long word (82 bits). 


Before the return to the point of down, with the level 1 interrupt 
pending, the kernel disables the critical out routines. This 
prevents access to an uninitialized controller during this phase. 


The power clear routines are driver and hardware specific. Power 
clear routines do whatever is necessary to restore the external 
devices to the state just prior to the power failure. This requires 
that the driver save information about the device state In a form 
that can be used by the power clear routine. For example, bus 
vectored devices provide an interrupt vector byte to the host as 
part of the interrupt cycle. The host uses this vector byte to 
calculate the interrupt vector that is assigned to the device. For 
maximum flexibility, most bus vectored devices allow the driver to 
pass the vector byte to the controller at run time. This is normally 
done only once, at system initialization, but it must also be done 
after a power failure. 


BUS ERRORS AND USER MEMORY SPACE 


Kernel modules, including drivers, should never access application 
data directly. Application programs often pass an incorrect 
address to the kernel in a system call. This usually happens as 
the result of some bug in the application program. Remember, a 
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development system that tends to crash when applications are 
being debugged is not going to be popular. The basic rule that 
must guide any system module development is that users should 
not be able to do anything that can crash the system. 


The kernel provides several routines that drivers can use to read 
or write application data. These routines protect the kernel against 
bus errors that, if not guarded against, would halt the system. Bus 
errors that occurs when an application is running cause the 
application to terminate, and a bus error when kernel code is 
executing Causes a panic. 


In all the examples given in this section, source and destination 
are pointers. 


The general routine used to handle bus errors in all the routines, 
except Dit, is setimp. The kernel setimp is a different routine than 
the library routine in section 3 of the programmer reference, but 
they are used in much the same way. The idea is to call setjmp, 
passing it a buffer where it can save the current state of the 
machine, and when it returns, make the access that is expected to 
Cause an error. If it does, the kernel restores the state of the 
machine from the buffer that was passed to sefjmp and execution 
resumes as a second return from sefimp. The two possible returns 
from semp are distinquished by the value returned by setjmp. If 
the return value is 0, then it is the first return. If it not 0, then an 
error has occurred and this is the second return. 


Any code that uses setjmp must include setjmp.h and have a 
definition of nofault. In the example below, notice that the code 
saves the address of the old buffer and restores it. Failure to save 
and restore the old buffer address is likely to bring about a system 
crash that can be difficult to debug. 


#include <sys/set jmp.h> 
extern int *nofault; /* Address of current jump buffer */ 


int jocheck (address) 
caddr_t address; 


{ 
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jmp_buf jb; /* jmb_buf: Jump buffer used to */ 
/* save the machine state. */ 
int *saved_jb; /* saved_jb: Used to save the */ 
/* address of the current buffer*/ 
int x; /* x: Used to save the return */ 
/* value. */ 


saved_jb = nofault; 


if (!setjmp (jb)) { 
/* Make jb the current jump buffer */ 
nofault = jb; 


/* Access the suspected address */ 
x = *address; 


/* No error set x to good */ 
x © 1 


} else { 
/* Bus error happened */ 
x= 0; 


} 
/* Restore the old jump buffer address */ 


nofault = saved_jb; 


return(x); 


The routine fustr is used to move null terminated strings between 
the kernel and application programs. It copies the source string to 
the destination string. The operation ends when the specified 
number of characters have been copied or when a null character is 
reached in the source string. If a null character is found, it is 
copied to the destination string. A 0 is returned if the copy 
completed successfully; a -1 is returned if a bus error happened 
while the copy was being done. As a note of caution, remember 
that this routine is designed to move ASCII strings; non-ASCII data 
is likely to have null characters that truncate the operation. For 
non-ASCIll data, use copyin and copyout. 


fustr (source, destination, number_of_characters); 
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For moving smaller quantities of data, there is another group of 
routines. The names all begin with either fu "Fetch User" or su 
"Set User" and end with the size of the data item that they move. 
The sizes are byte and word; ~ a 4 byte quantity. The two routines 
fuword and fubyte return a data item read from the application’s 
memory. All four routines return a -1 if an bus error is detected; 
suword and subyte return a 0 if no error is detected. 


w = fuword (source); 
c = fubyte (source); 


suword (destination, source); 
subyte (destination, source); 


The function iomove is designed to be used in conjunction with 
the read and write system calls. It is controlled by a combination 
of its parameters and fields in the wu structure. The three 
parameters are a kernel buffer, a number of bytes to be moved, 
and a flag that determines the direction of the transfer. This flag is 
either B_READ or B_ WRITE. B READ is taken to mean that 
iomove is being called from a read system call and that the transfer 
should be from the kernel to the application. The other flag, 
B_ WRITE, means that the system call is a write and the move is 
from application memory to kernel memory. 


/* Move data from the kernel to the user */ 
fomove (kernel_buffer_address, n_of_bytes, B_READ); 


/* Move data from the user to the kernel */ 
jomove (kernel_buffer_address, n_of_bytes, B_WRITE); 


The application’s buffer address is in the field u.u_base. After 
iomove has finished, it increments u.u_base and u.u_ofset by 
n_of_bytes. It also decrements u.u_count by n_of_bytes. There 
is one more thing; the u.u_segflg should be 0. If it is a 1, the 
transfer is done without bus error protection. /omove sets 
u.u_error to EFAULT if a bus error happens. Also, jomove uses 
copyin and copyout and they use Dif. 
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Perhaps the two most flexible routines are copyin and copyout. 
Copyin copies into the kernel and copyout copies out to an 
application buffer. These routines return -1 if a bus error occurs 
and a 0 if successful. 


copyin (source, destination, number_of_bytes); 
copyout(source, destination, number_of_bytes); 


Another useful routine is bit. This routine provides no protection 
against bus errors and so should not be used to copy between 
application memory and kernel memory. However, it is the fastest 
way to move blocks of data around within the kernel. 


bit (destination, source, number_of_bytes); 


ERROR LOGGING 


The following sections describe the error logging structures and 
provide examples for error logging routines. 


Communicating Errors To Application Processes 


When a system call results in an error, the kernel or driver module 
that detects the error sets the u_error field in the u structure of the 
process that issued the system call. The valid settings of the 
u_error field are explained in the introduction to section 2 of the 
programmer reference. When the kernel returns from the system 
call with u.u_error set, it causes the system call to return a -1 and 
the errno variable is set equal to the u_error field. For example, 
the code fragments below describe an attempt by an application to 
open an invalid device. 


/* Application Code */ 


#include <errno.h> 
extern int errno; 
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if ((fd = open("/dev/x105", O_RDWRT)) == -1) { 
/* Open failed */ 
printf ("Unable to open /dev/x105. Errno = %d\n", 


om errno); 
/* 
* See perror in the programmer's reference 
* 
perror("Unable to open /dev/x105."); 
exit(1); 


/* Kernel Code */ 
#include <sys/errno. h> 


xlopen (dev) 
dev_t dev; 
{ 
/* X1 controller only supports subdevices 0, 1, 2, and 3 */ 
if (minor(dev) > 3) { 
oo” /* Invalid sub device number */ 
: /* ENXIO: Bad address or no device. */ 
u.u_error = ENXIO; 
return; 


Logging Hardware Events 


Specific details of hardware errors are not reported to application 
processes. These details are stored in a log file 
(/usr/adm/errfile), and a system utility (errpt(1)) is provided for 
reading it. When a hardware error occurs, the driver creates an 
error record and places it in the in-memory error log. The in- 
memory error log is written out to the log file (/usr/adm/errfile). 


Errpt reads the error records from /usr/adm/errfile, interprets 
them, and prints them for a user to inspect. If the driver logs 
errors, add code to this utility to print these error records. 
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Error include Files 
The error logging interface has three include files. 


/usr/include/sys/elog.h 
/usr/include/sys/erec.h 
/usrfinclude/sys/err.h 


The file elog.h contains structures that are used by block device 
drivers to collect statistics such as number of operations 
performed and number of unlogged errors. These statistics are 
logged whenever an error is logged. Elog.h also contains a set of 
definitions of major device numbers for logging purposes. These 
major numbers are different than the ones used in special device 
nodes. They are used as indexes and switch codes in errpt. 
Drivers that intend to log errors must add a major number to this 
list. 

Erec.h contains definitions of standard error records, such as the 
error record that is logged when a power failure happens. There is 
a list in this file of error record types. These error record types are 
used in errpt to invoke the correct routine to print a record. Ifa 
driver intends to log a new error record type, then a new type 
code must be added to this list. 


The last file is err.h which contains structures that define the error 
log. 


Character Device Error Logging 
Character device error logging requires three steps. 
1. Get space in the error log for the driver's error record. 


2. Fill in the fields of the error record with the information that 
describes the problem. 


3. Place the record in the log. 
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Drivers get space in the error log by using getes/ot. This routine 
accepts the size of the record to be logged and returns a pointer 
to a buffer large enough to hold it. If no space is available in the 
error log, getes/ot returns a null pointer. 


struct errhdr *geteslot (size) 
int size; 
{} 


The driver fills the error record by redefining the pointer returned 
by getes/ot as a pointer to a driver error record and then loading 
the fields according to the type of the error. 


An error is logged by passing its address and type to puterec. 
Puterec places the time and the error type into an error header 
structure 

that precedes the user defined error record, and then logs the 
whole structure. The error type mentioned above is the type 
defined by the user and added to the list in erec.h. 


The example below shows a driver logging a checksum error. 
Notice that the driver keeps a count of unlogged errors and logs 
that number when an error is successfully logged. The makedev 
macro builds device numbers from major and minor numbers. It is 
defined in sysmacros.h. Also, the major number XYZO is the one 
added to the list in elog.h. 


It is good practice to place developer defined structures in include 
files. The driver and errpt can share the same include file. 


/* Error Include File xyzerr.h */ 
/* Error codes */ 
#define CKSUMERR (1) 


struct xyzerr { 
dev_t edev; 
int ecode; 
int eulogd; 


}; 
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Now the driver code: 


/* Driver Source Code */ 
#include <sys/sysmacros.h> 
#include <sys/elog.h> 
#include <sys/erec.h> 
#include <sys/err.h> 
#include <sys/xyzerr.h> 


struct xyzerr *ep; 
int unlogged = 0; 


if ((ep = (struct xyzerr *)geteslot(sizeof(struct xyz))) J= NULL) { 
ep->edev = makedev (XYZO, logical_unit); 
ep->ecode = CXSUMERR; 
ep->eulogd = unlogged; 


puterec (ep, XYZtyp); 
} else { 

+tun logged; 
} 


Block Device Driver Error Logging 


Error logging in block device drivers is more structured than error 
logging for character devices. Block device driver developers 
must add a major number to the list in efog.h; but, they do not 
need to add a error record type to the list in erec.h. A standard 
error record type has been defined for block device drivers. 


Information logged for block devices comes from the subdevice's 
queue header and from the buffer header for the I/O request that 
caused the error. Block device error logging routines assume that 
the first buffer header in the queue caused the error. 


The first open for the subdevice must create the fields in the 
queue header. Remember, the queue header is defined in jobuf.h. 
The first field in the queue header is b_dev. The driver makes the 
value for the b_dev field by combining the error log major number, 
from the list in elog.h, with the subdevice number. The macro 
makedev can be used to do this. 
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The second field, io_sip, is a pointer to the subdevice’s 1|/O 
statistics block. The keeping of I/O statistics by block devices is 
explained fully in the next section. 


The last two fields are closely related. They define the address 
and size of a block of data that the driver developer wants placed 
in the log. The field io_adar contains the address of the block and 
io_nreg contains the number of 16-bit quantities that make up the 
block. 


This mechanism was originally intended to log device registers. 
The present disk drivers use it to log their I/O control blocks. 
These I/O control blocks are data blocks in memory that describe 
the I/O operation to the controller. 


The block device error logging interface contains two routines. 


Fmtberr creates an error record and prepares it for logging; logberr 
enters the record created by fmtberr into the log. Drivers also call 
fmtberr to log retries. 


Fmtberr is called once when an error is detected and once for 


each retry. The parameters passed to fmtberr are: the address of 


the queue header for the subdevice that experienced the error and 
the physical block number of the first block in the partition (see the 
section on partitions). 


Logberr is called when the driver is ready to log the error. This 


happens when the driver’s error recovery efforts end either 


successfully or otherwise. Two parameters are passed to /ogberr, 
the address of the queue header for the device that had the error 
and a flag that specifies the disposition of the error. If the flag is a 


0 the error is logged as recovered; if the flag is a 1 the error is 
logged as unrecovered. 


Block device drivers set a bit in the global variable blkacty 


whenever they are accessing the bus. This variable is logged by 


fmtberr to give information about simultaneous bus activity. Each 
driver is assigned the bit that corresponds to the driver's error log 
major number. Drivers should set this bit just prior to issuing a 
command to their controller and clear it when they receive an 
interrupt. 
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/* Set the bit */ 
bikacty j= (1 << XYZ0); 


/* Clear the bit */ 
bikacty &= (1 << XYZ0); 


Block Device I/O Statistics 
Block device drivers collect statistics that are used to calculate 
estimates of error rates and I/O system performance. The data 
collected includes: 

e Number of I/O operations done. 

¢ Number of non-!/O operations done. 

e Number of blocks transferred. 

e Number of unlogged errors. 

« Amount of time that the controller was busy. 

e Amount of time between an operation being received by the 


driver and its completion. 


The structure used to collect statistics is defined in elog.h; its 
name is jotime. Each subdevice’s statistics are kept in its element 
of an array of ioume structures. 


struct iotime zyzstat[N_of_SUBDEVs]; 


When a subdevice is opened for the first time, the field fo_sép in 
its queue header must be made to point to the /ostat field in the 
subdevice’s /otime structure. 


zyzutab[minor(dev)].io_stp = &xyzstat[minor(dev)].ios; 
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The /ostat structure contains three fields The first field, io_ops, is 
used to count the number of I/O operations that the device has 
done. The second field, io_misc, is used to count non-i/O 
operations. The third field is not used by the driver directly. 
Fmtberr uses io_unlog to count errors that it could not log due to a 
lack of error log space. The jos field is logged by fmtberr. 


The remaining fields of the jotime structure are: io bent, io_act, 
and io_resp. The io_bent field is used to total up the number of 
512 byte blocks transferred to or from the subdevice. The kernel 
keeps a global variable named /bolt. Lbolt contains a count of the 
number of ticks of the system clock since the system was booted. 
Therefore, /bo/t divided by HZ gives the number of seconds since 
the system was booted. The constant HZ is defined in param.h. 


The jo_act field is used keep a total of the time that the controller 
is busy. The driver does this by setting the field jo_start in the 
subdevice’s queue header equal to /bo/lt when a command is 
issued to the controller. When the command is completed the 
driver subtracts the value of jo_siart from the current value of /bolt 
and adds the result to io_act. The last field is used to keep a total 
of the time between a I/O request being received by the driver and 
the request being completed. This is accomplished by saving /bolt 
in the b_start field of the buffer header when the request is 
received. When the request has been compieted, just before the 
driver calls iodone, b_ start is subtracted from /bo/t and the result is 
added to jo_resp. 


/* In the strategy routine */ 
bp->b_start = Ibolt; 


/* In the routine that issues the command to the controller */ 
xyzutab[minor(bp->b_dev)].{o_start = lbolt; 


/* In the interrupt service routine */ 
sdn = minor(bp->b_dev); /* Subdevice number */ 
zyzstat[sdn].{o_act += Ibolt - xyzutab[sdn]}.{o_start; 
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/* In the routine that releases the completed 1/0 request */ 
xyzstat[minor(bp->b_dev)].fo_resp += Ibolt ~ bp->b_start; 
fodone (bp); 


Diagnostic System Call 


The in-service diagnostic system call accepts two parameters: a 
null terminated string containing the name of the device, and a 
pointer to a structure containing information that describes the 
diagnostic request. Each driver must define its own structure. 


struct xlarg xl_arg; 


inserv ("h801", &x1_arg); 


At the driver level, the interface consists of an array of pointers to 
device names and the inservice diagnostic routine. The name of 
the array of pointers is nam preceded by the handler prefix 
specified in the master file (see Chapter 3). The last entry in the 
array is a null pointer. The example below is taken from the 
system's 8-inch disk driver. Notice that all possible devices and all 
possible variant spellings are represented in the array. The kernel 
uses this array to identify the driver that handles the device named 
in the inservice diagnostic system call. 


char *wdnan[]) = { 
"n501", 
*n502", 
"H501", 
"H502", 
(char *)0}; 


The inservice diagnostic interface routine in the driver is named 
xyzdig (xyz is handler prefix) It receives the two parameters that 
were passed to the inservice diagnostic system call. The device 
name string has already been copied by the kernel into the kernel 
environment; but, the driver must copy in the diagnostic structure. 
Remember to use copyin and copyout. 
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xldig (devnme, diagstructure) 
char devname[]; 
Structure xlarg *diagstructure; 


The main implementation problem is how to gain control of the 
hardware. Diagnostic requests are received asynchronously with 
regular I/O requests. The driver needs to have some mechanism 
for halting the processing of regular I/O operations, doing the 
diagnostic, and resuming regular I/O processing. In the system's 
disk drivers, this is accomplished by having the diagnostic 
interface routine queue a special buffer header and go to sleep to 
wait for the diagnostic to be completed. The special buffer header 
is defined within the driver and is not part of the kernel’s buffer 
pool. When the start routine reaches that buffer header, it invokes 
a diagnostic operation routine to do the requested diagnostic 
operation. When the diagnostic operation is completed, the 
diagnostic operation routine wakes up the diagnostic interface 
routine, clears the driver busy fiag, and calls the start routine to 
resume processing of regular I/O. If the diagnostic operation 
causes an interrupt, then the interrupt service routine must invoke 
the diagnostic operation routines. 
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CONTROLLER PORT DEFINITIONS 


Port Assignments 


Port Address* Port Width Def inition 


M+0 Mailbox Register 
M+0 Mailbox Diagnostics Status 
M+ 4 Interrupt Vector Register 


M+6 Soft Arbiter/Int. Status Reg. ** 


*M = Board base address. This address is defined as the firmware default 
address combined with the specific board strapping. 


** The Soft Arbiter/Interrupt Status Register can be accessed by a byte 
read at M + 7 or a word read at M+ 6. (The upper byte of the word is 
valid.) 


Mailbox Register - 32 bits 


The mailbox is addressable using word or long word references. 
No byte operations. 

Writing to M + 2 interrupts HPSIO local processor. 

Reading "M + 2" clears interrupt from HPSIO local processor. 
Reading or writing "M" has no affect on interrupt. 
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Access to mailbox register must be coordinated with HPSIO 
local processor through use of soft arbiter. 

Intended to be used to pass addresses of IOPBs. 

First read after controller diagnostics shows diagnostics status. 


Mailbox Register Diagnostics Status - 16 bits 


Channel 0 Error Indicator 
Channel 1 Error Indicator 
Channel 2 Error Indicator 
Channel 3 Error Indicator 
Channel 4 Error Indicator 
Channel 5 Error Indicator 
Channel 6 Error Indicator 
Channel 7 Error Indicator 
Level-0 Test Running | 
Level-0 Completion Status 


Critical Board Error Code 


Channel x Error Indicators 
0 = No error 
1 = Channel degraded 


Level-O Test Running 
If Bit 12 = 1, then these four bits show 
the HPSIO Level-0 test currently running. 


Level-O Completion Status 
0 = Controller Level-0’s not running 
1 = Controller Level-0’s in progress 


Critical Board Error Code 
0 = No error 
1 = ROM checksum error 
2 = RAM stuck bit/address decode error 
3 = Mailbox register stuck bit error 
4= All channels degraded error 
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Interrupt Vector Register - 16 Bits 
Bits Definition 


0-7 Vector to be supplied to PMC when HPSIO 
generates an interrupt to Multibus; 
R/W from Multibus. HPSIO processor 
has no access to this. 


8-10 Interrupt level assigned to HPSIO when it 
generates Multibus interrupts; should be 
selected as one of the "Bus Vectored" 
levels of the PMC and is read/write from 
Multibus. HPSIO processor has no access. 


11 Defined to enable (=0) or disable (=1) 
interrupts from HPSIO processor to Multibus. 
R/W from Multibus. HPSIO processor 
has no access. 


12-15 Reserved. Should be zero 


Soft Arbiter/Interrupt Status Register - 8 Bits 
Bits Definition 


0 = 1 if HPSIO processsor has pending interrupt 
from PMC write to "M + 2" mailbox register. 
Cleared when HPSIO processor reads "M +2" 
mailbox register. 


1 = | if PMC has pending interrupt from HPSIO 
processor write to "M+2" mailbox register. 
Cleared when PMC reads "M+2" mailbox register. 

2-5 Reserved. No meaning. 

6 “ACK 1" function for the software arbiter; 


controls access to the mailbox register. 
May be read by HPSIO Processor and from 
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Multibus but only written by HPSIO 
processor. 


4 "REQ2" function for the software mail 
box arbiter. Readable by both local processor 
and from Multibus; written only from 
Multibus. 


NOTE: DO + Di simultaneously = 1 is an error condition 
which signals a failure to follow soft arbiter protocol. 


CIOPB STRUCTURE 


Mnemonic 


FUNC 
STAT 
CHAN 
CBAUD 
CMODE? 
CMODE2 
CSTAT 
ICNTRL 
DSTAT 
DCHAR 
DSTAT 
BUFAD 
BUFLEN 


Hex Length 


A-4 


Bytes 


NO ne ae ee 


Structure Definition 


Description 


Function Code 

Return Status 

Channel number 

Trans. Rate; Signal Control 
Parity Type; Char. Length 
No. Stop Bits; Oper. Mode 
Line Status 

Interrupt Control/SRQ 
Character Status 
Received Character 
Character Status 

Buffer Start Address 
Buffer Length 
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CIOPB Field Definitions 


o~ FUNC: 


Hex Value Description 


1 Channel Initialization 
2 Character Acknowledgement 
3 Configure Interrupt 
4 Output 
5 Reserved 
STAT: 


See LIOPB definition for STAT field 


CHAN: 
DUART channel number. 
Valid numbers range from 0 to 7. 


| CBAUD: 
Bits Definition 


0-3 BAUD Rate 

4 Break Control 

> Enable Input Control 
6 RTS Contro! 

7 DTR Controi 


BAUD Rate 
0 = 75bps 
1=110 
2= 134 
3 = 150 
4 = 300 
5 = 600 
; 6 = 1200 
7 = 2000 
8 = 2400 
9=4800 — 
A(hex) = 180 
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B(hex) = 9600 

C(hex) = 19200 
Break Control 

0 = Normal 

1 = Force Break 


Enable Input Control 
0 = Disable Input 
1 = Enable Input 


RTS Control 
0 = Force RTS Output Low (Off) 
1 = Force RTS Output High (On) 


DTR Control 
0 = Force DTR Output Low (Off) 
1 = Force DTR Output High (On) 


CMODE1: 
Bits Definition 
0-1 Character Length 
2 Parity Type 
4 Parity Enable 
Character Length 
0 = 5 bit character 
1 = 6 bit character 
2 = 7 bit character 
3 = 8 bit character 
Parity Type 
0 = Even parity 
1 = Odd parity 
Parity Enable 


0 = Enables parity 
1 = Disable parity 


A-6 
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CMODE2: 
Bits Definition 
0-3 Stop Bit Length 
4-5 Reserved (should be zero) 
6-7 Operational Mode 


Stop Bit Length 
7 = 1 Stop Bit 
F(hex) = 2 Stop Bits 


Operational Mode 
0 = Non-echo 
1 = Auto-echo 
2 = Local Loopback 
3 = External Loopback 


CSTAT: 
Bits Definition 
0 DSR State 
1 DCD State 
2 CTS State 
3-7 Reserved (should be zero) 
xxx State 
0 = Signal xx Low Status (Off) 
1 = Signal »« High Status (On) 
ICNTRL: 
Bits Definition 


0 Receiver Interrupt Enable 

1 Input Line change Interrupt Enable 

2 Receiver SRQ (Host read only) 

3 Input Line Change SRQ (Host read only) 
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Receiver Interrupt Enable 
0 = Disable "Character Available" Interrupt 
{1 = Enable “Character Available“ interrupt 
Input Line Change Interrupt 
0 = Disable Delta Line Change Interrupt 
1 = Enable Delta Line Change Interrupt 


Receiver Service Request 
0 = No service request 
1 = Service request for "Data Character Available" 


Input Line Change Service Request 
0 = No service request 
1 = Service request for Delta line change status 


DSTAT: 
Bits Definition 
0-3 Reserved (should be zero) 
4 Overrun status 
5 Parity status 
6 Framing status 
i Break status 


Overrun Status 
0 = No overrun error 
1 = Overrun error 


Parity Status 
0 = No parity error 
1 = Parity error 


Framing Status 


0 = No framing error 
1 = Framing error 
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Break Status 
0 = No break condition 
2, 1 = Break condition (not necessarily an error) 

DCHAR: 

This field is used to store the data character input (through a 
DUART) to system memory. The transmission status of this 
character is in the DSTAT field. | 

BUFAD: 


System memory logical address of the output buffer with an output 
function. 


BUFLEN: 


Length in bytes of the output buffer specified by the BUFAD field. 
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DEVICE DRIVER CLISTS 


Clists are queues of characters used by the kernel. Clists consist 
of one or more cblocks. Each cblock holds up to 64 characters. A 


free list, called cfreelist, is maintained to keep track of available 
cblocks. 
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CLIST DEFINITIONS 


These definitions are found in the file /usr/include/sys/tty.h. 


* A clist structure is the head of a linked list queue of characters. 
* The routines getc* and putc* manipulate these structures. 


struct clist { 
int ¢_cc; /* character count */ 
struct cblock *c_cf; /* pointer to first */ 
struct cblock *c_cl; /* pointer to last */ 


4 
fdefine CLSIZE 64 
struct cbiock { 
struct cblock *c_next; 
char c_first; 
char c_last; 
char c_data[{CLSIZE}; 


= 

struct chead { 
struct cblock *c_next; 
int c_size; 
int c_flag; 

}; 


extern struct chead cfreelist; 
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CBLOCKS AND CLISTS 


co” Each cblock contains: 


c_next 

Pointer to the next cblock in the list. 
c_first 

Index of next character in the cblock to be read. 
c_last | 

Index of next character in the cblock to be written. 
c_dOata 

Index of an array of 64 characters. 


Each clist consists of: 


The total number of (unread) characters in the clist. 
Pointer to the first cblock in this clist. 


Pointer to the last cblock in this clist. 


CBLOCK FREE LIST 


A free list is maintained to keep track of available cb/ocks, for fast 
allocation to a clist. The number of cblocks reserved is the clists 
configuration parameter. The cfreelist structure heads the free list, 
and contains: 


c_next 
Pointer to the first available cbiock. 
c¢_size 
om Number of characters per cblock (64 for this system). 
c_ilag 
If set, processes are waiting for a cblock 
(wakeup will be issued when one is freed). 
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The cblocks on the free list are singly-linked using the c_next 
field. 


CHARACTER BUFFERED I/O DIAGRAMS 
The following diagrams show the general relationship between 


cblocks, a clist, and the free list for the kernel calls that influence 
these structures and buffers. 
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Clists 


getc 


Initial state of clist p and cfreelist 


cblocks 


clist p 


c_next °* 
C_first = 62 
c_last = 64 
a 


c__next = 0 

C_first = 0 

c_last = 63 
A 


cfreelist cblocks 


c_next ° 
C_size = 64 
c_flag = 0 


NOTE: The characters in a cblock are referenced by an 
index between 0 and 63. 


UP-12230 R1 | B-5 


Appendix B 


End of first getc operation on the clist p 


cblocks 


clist p 


c_next * c__next = 0 
c_first = 63 c_first = 0 
c_last = 64 c_last = 63 


cfreelist 


c__next 
c__size = 64 
c_flag = 0 


The character ’Y’ is returned. 


NOTE: The c_first field of the cblock is incremented to 63 
to indicate the next character to read, and the number of 
characters in the clist itself is decremented by 1. 
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Clists 


End of second getc operations on the clist p 


cblocks 


clist p 


cfreelist cblocks 


c__next 
c__size = 64 
c_flag = 0 


c__next 

C_ first = 64 
c_last = 64 
a 


cnext = 0 


The character ’2Z’ is returned. 


NOTE: Because the entire cblock has been read, it is 
returned to the free list. Both c_cf and c_cl point to the 
only cblock in the clist, and c_cc is decremented. 
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End of many getc operations on the clist p 


cblocks 


c__next = 0 
c__first = 62 
c_last = 63 
A 


cfreelist cblocks 


cnext = 0 
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End of next getc (clist is empty) 


cfreelist cblocks 
c__next c__next c__next cnext = 0 
c__size = 64 cC_first = 63 C_first = 64 
c_fiag = 0 cC_last = 63 c_last = 64 
a a 
ce” 
The character ’L’ is returned. 
NOTE: Because the entire cblock has been read, it is 
returned to the free list. Both c_cf and c_c/ have the value 
0 which indicates no cblocks on list. 
The getc (p) operation returns a value of -1. 
on 
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putc 


Initial state of clist p and cfreelist 


ZS cblock A 5 cblock B 
cfreelist 


Each time putc(c, p) is called, the character is added to the last 
cblock in the clist p. 


cblock added to clist 


cblock A cblock B cblock X 


cfreelist 


= 


When the last cblock becomes full, putc adds another block to the 
clist. In the example cblock X is added. 


When pute fails because no more blocks are available on cfreelist, 
the the value -1 is returned rather than zero. 
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Clists 


getcf 
initial state of cfreelist 
cfreelist 


cblock X cblock Y cblock Z 0 


Each time geicf() is called , an element on cfreelist is removed and 
its address is returned. 


Result of cp1 = getcf(); 


cfreelist 


cpt 


cblock X 
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Result of cp2 = getcf(); 


cfreelist 


cblock Z 0 
cpl cp2 
Result of cp3 = getcf(); 


cfreelist 


cn 


cb1 cb2 cb3 
cblock X cblock Y i cblock Z 
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Clists 


Result of cp4 = getcf(); 


oo Cfreelist 


[a= 


cpl cp2 cp3 1 
0 
cblock X cblock Y | eblock Z| 


The value 0 is returned if the cfreelist is empty. 


putcf 
co 
initial state of cfreelist and variables cp1, cp2, And cp3 
Cfreelist 
Tae} 
cp1 cp2 cp3 
o™ 
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Result of putcf(cp1); 


cpt 


cblock X 


cp2 cp3 


Result of putcf(cp3); 


cfreelist 


cfreelist 


cblock Y 


The putcf operation cannot return an error. 
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Clists 


getcb 
cf 
Initial state of clist p 
p 
L [men] [aoe] 
Result of cb1 = getcb(p); 
p 
: 
c™ | 
cb1 
om 
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Result of cb2 = getcb(p); 


p 
| 
cblock A cblock B 


Result of cb3 = getcb(p); 


p 
0 
Boe an, 
cb1 cb2 


B 
0 


cblock A | eblock B 


The value 0 is returned if there are no more cblocks on the clist. 
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Clists 


a Se 


putcb 
Initial state of clist p and variables cb1, cb2, and cb3 
p 
0 
a Po 
cb1 cb2 ‘ 
0 
> Result of putcb(cb1, p); 
| 
p cb1 
= : 
cb2 e 
0 
a 
| 
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Result of putcb(cb2, p); 


p 
"= cblock A ~ oblock B ; 


cb1 . cb2 


The putcb operation cannot return an error. 


putcbp 


Initial state of clist p, cfreelist, and character buffer cp 


i Ww 
[Tz : 
list | cblock A buffer 
of -n 
cfreelist characters 
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Result of cnt = putcbp (p, cp, n) 


cfreelist : 


cp 
=e = | ||- 


cnt = putcbp (p, cp, n) 


The following is attempted: Characters from cp are added to the 
clist (p). Cnt is the number of characters actually added to the clist. 
In this case, cnt =n. 


Result of cnt = putcbp (p, cp, n) 


cblock A cblock B cblock C 


cfreelist 


cp 
chead 0 } ent 
-n 


cnt < n (Partial buffer transferred) 


When cfreelist becomes empty, not all characters can be added. 
In this case cnt is less than n. 
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getcpb 


Initial state of clist p and character buffer cp 


8) cp 
{‘— por -n 
cblock A cblock B 


Result of cnt = getcbp (p, cp, n ) 


p cp 
[= ; 
= 


An empty buffer pointed to by cp is filled from the clist. 


Result of cnt = getcbp (p, cp, n) 


Cnt records the number of characters actually moved to the buffer 
cp. When the clist becomes empty this will be less than n. 
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Bootable Media 


OVERVIEW 


After a new kernel is created, it can be loaded into the system 
(booted) and tested. Take these steps on the test system to boot 
a new kernel. 


1. Perform a system shutdown. Logging in as shutdown 
performs an orderly shutdown. 


2. Set the MANUAL/AUTO LOAD switch to the MANUAL position. 

3. Reset the machine by engaging the RESET switch. 

4. Choose the LOAD option from the Startup Menu. 

5. Type in the media device name (refer to page C-4 for a listing 
of device names and types) and the full path name of the 
kernel if required. This starts the load of the kernel. This step 
is slightly different depending on the media being used. 

6. Enter <space> to begin execution of the kernel. 

There are three different types of media that can be used to boot: 

hard disk, flex disk, and streaming tape. in the following 


examples, it’s assumed that the kernel /driver/test.unix needs to 
be tested. 
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HARD DISK BOOT 


If the development system and the test system are the same, it is 

ideal to use the hard disk to load from. If the first 5.25 inch hard Wy 
disk contains the file /driver/test.unix, the device name h501 for 

the 5000/30 and 5000/50, or sda1 for the 5000/35 and 5000/55, 

and the path name /driver/test.unix are entered. 


FLEX DISK BOOT 


The flex disk can be used when the development system and the 
test system are different. The flex disk must be formatied with a 
bootblock and an Initial System Loader (ISL). The following 
command formats the flex disk: 


$ /etc/format -d /dev/rfdsk/c0d0s0 
A file system must be put on the disk using this command: 


$/etc/newfs -s 1 £501 (for the 5000/30 and 5000/50) wo 
$/etc/newfs -s 1 sfdl (for the 5000/35 and 5000/55) 


Now the test kernel must be copied to the flex disk with these 
commands: 


$ /etc/mount /dev/fdsk/c0d0s0 /mnt/fd70 
$ cp /driver/test.unix /mnt/fd70 
$ /etc/umount /dev/fdsk/cOd0s0 


The flex disk can now be moved to the test system. With the 
LOAD switch on Manual, reset the system. When the device name 
is requested, enter F501 (for the 5000/30 and 5000/50), or sdf 
(for the 5000/35 and 5000/55), then enter /test.unix for path name. 
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STREAMING TAPE 


Streaming tape can also be used if the development system and 
the test system are different. This is faster than the flex method. 
The tape must have two files: 


A streaming tape boot block. 
The object of the kernel. 


The object of the kernel must be extracted from the kernel a.out(4) 
file before copying to tape. The first 168 bytes of an a.out file are 
header information and must be stripped out. The following 
command strips out the unneeded information. 


dd if=/driver/test.unix of=/driver/tape.unix ibs=168 skip=1 


The streaming tape boot block and the stripped kernel can be put 
on the tape using the following two commands. 


$ dd if=/sys/boot/boot.stp of=/dev/rstp/Oyn 
$ dd if=/driver/tape.unix of=/dev/rstp/Ony 
NOTE: The tape device must not rewind after copying the boot 


block or before copying the kernel object. 


The tape can be loaded on the first or second tape drive using the 
device name st01 (for the 5000/30 and 5000/50) or ssg1 (for the 
5000/35 and 5000/55). No path name is requested. 
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Firmware 


Device 
Name 


Mass 


Storage 
Device 


Rel. Rel. 
2.00 1.03 
& above | & below 

NA 


5000 


Series 
System 


Device 
Type 


5000/20 MSC Int. Disk Yes 
st01 Int. Tape NA No 
fd01 Int. Flex NA No 


Int. Disk Yes Yes 
Int. Tape No No 
Int. Flex No No 


5000/30 MSC h501 
st01 
fd01 

5000/35 | SMSC sda 

& HPMSC ssg1 
sfd1 


SHA sd01-sd03* 
& HPMSC | sd11-sd13* 
a 


sd21-sd23* 
sd31-sd33* 

*On the 5000/35, the third disk is available only if the 5000/55 

expansion cabinet is used. 


Int. Disk 
Int.Tape 
Int. Flex 


ss61-ss41 


Int. Disk 
Int. Disk 
Int. Tape 
Int. Flex 


Figure C.1. Device Names 
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5000/50 


5000/55 


Storage 
Device 


MSC 


SMSC 
& HPMSC 


SHA 
& HPMSC 


Figure C.1. 
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Device 
Name 


sd01 
sd02-sd03 
sdii-sd13 
sd21-sd23 
sd31-sd33 
ss61-ss41 


sda1-sdb1 
ssgi-ssf1 
sfd1 


sd01-sd03 
sdi1i-sd13 
sd21-sd23 
sd31-sd33 
ss61-ss41 


Device 
Type 


Int. Disk 
Int. Disk 
Int. Disk 
Int. Tape 
Int. Flex 


Ext. Disk 
Int. Tape 
Int. Flex 


Bootable Media 


| Root Device | Device 
oot Device _ Rel. 
2.00 1.03 
& above | & helow 


Device Names (Cont. ) 
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Appendix D. 
Kernel Calls 


This section describes the primary driver relatéd kernel calls in 
alphabetical order. These calls execute in kernel user space and 
reside in the "C" libraries, libO -lib9. 


NOTE: Refer to the Tuning Guide for additional information 
on kernel parameters that influence the use of kernel 
memory. 


bit 
copyin 
copyout 
cout 


dmamalloc 
dmapit 
fubyte 
fustr 
fuword 
getc 
getcb 
getcbp 
getcf 
geteslot 
iodone 
iomove 
klalloc 
passc 
physio 
printf 
putc 
putcb 
putcbp 
putcf 
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D-2 


puterec 
setimp 
sleep 
spl 
subyte 
suword 
timeout 
wakeup 
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NAME 
bit 


SYNOPSIS 
int bit(dest, src, count) 
char *Src; 
char *dest; 
int count; 


DESCRIPTION 7 
Move a block of data between src and dest with no checking 
for bus errors. This is an optimized memory copy routine. 


RETURN VALUE 
no meaning 
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NAME 
copyin 
SYNOPSIS 
int copyin(src, dest, count) 
char *src; 
char *dest; 
int count; 


DESCRIPTION 3 
Copy count bytes from src in user space to dest in kernel 
space. 


RETURN VALUE 
-1 bus error 
otherwise success 
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NAME 
copyout 


SYNOPSIS 
int copyout(src, dest, count) 
char *src; 
char *dest; 
int count; 


DESCRIPTION 
Copy count bytes from src in kernel space to dest in user 
space. 


RETURN VALUE 
-1 bus error 
otherwise success 
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NAME 
cout 
©) synopsis 
coutb(register_addr, data) 
char *register_addr; 
char data 
coutw(register_addr, data) 
short *register_addr; 
short data 
coutl(register_ addr, data) 
int *register_addr; 
int data 
DESCRIPTION 
These routines are used by some drivers to handle the writing 
to device registers. They simply copy the specified amount of 
data to the specified register except during power fail 
en recovery when the routines are disabled and do nothing. 
Some devices behave disastrously if they have not been initial- 
ized before giving them commands. The critical out routines 
are used to protect against this. 
RETURN VALUE 
none 
oo 
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CPASS (k) 


NAME 
cpass 
= SYNOPSIS 
int cpass( ) 


DESCRIPTION 
Return a character from user space. The source address is 
u.u_base. U.u_count is decremented. U.u_offset and 
U.u_base are incremented. Error checking is performed so 
user addresses do not have to be validated before using this 
function. If an addressing error occurs, u.u_error is set to 
EFAULT. 


RETURN VALUE 
QO The transfer is correct. 


-1 Two possibilities 


1. The value of u.u_count is 0 and no more characters 
can be transferred. 


> 2. A fault has occurred and the value of u.u_error has 
been set to EFAULT. 
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NAME 
dmamalloc 


SYNOPSIS 
int dmamalloc(size) 
int size; 


DESCRIPTION 

Allocate enough page blocks to map a buffer of the size speci- 
fied by an argument to the function. The number of page 
blocks available to a given driver is two. Refer to DMANPB in 
the Tuning Guide. The value returned from this function iden- 
tifies the first page block and should be saved for use in the 
function dmapit. If no page blocks are available, sleep until 
they become available. 


RETURN VALUE 
pageblock identifier 
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NAME 
dmapit 
SYNOPSIS 


dmapit(segloc,pageloc,ladr,bytecount,ptepp) 
int segloc /* segment in context 31 allocated at confi- 


guration */ 
int pageloc /* page block reserved by dmamalloc */ 
int ladr; /* pointer to user space */ 


int bytecount /* number of bytes to map */ 
int *ptepp; /* pointer to user's page table entry */ 
DESCRIPTION 
The MMU described by segloc, pageloc, and bytecount is ini- 
tialized with the physical addresses defined by ladr and ptepp. 
This call puts values in the segment registers for context 31 
and the page registers in the identified pageloc. 
RETURN VALUE 
no meaning 
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NAME 
fubyte 


oo SYNOPSIS 
int fubyte(src) 
char *src; 


DESCRIPTION 
Fetch user byte. Return one character from user space 
addressed by src. 


RETURN VALUE 
“1 bus error 
1-255 success 
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NAME 
fustr 


™ SYNOPSIS 
int fustr(src, dest, count) 


char *SIc; 

char *dest; 

int count; 
DESCRIPTION 


Copy a string between kernel and user space. Characters are 

copied from source to destination until a null character is 
transferred or until count number of characters have been 
transferred. 


RETURN VALUE 
-1 bus error 
O success 
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NAME 
fuword 


SYNOPSIS 
int fuword(src) 
int *src; 
DESCRIPTION 


Fetch user word. Return one word from user space 
addressed by src. : 


RETURN VALUE 
-1 bus error 
otherwise success unless value returned from user space is -1 
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NAME 
getc 


SYNOPSIS 
int getc(p) struct clist *p; 
DESCRIPTION 
Return a character from the clist pointed to by p. P is nor- 


mally allocated by the user. This routine does suspend and 
may therefore be called from an interrupt service routine. 


RETURN VALUE 
-1 The clist p is empty. 


0..255 value of the character which has been removed from 
the clist 
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NAME 
getcb 


SYNOPSIS 
int getcb(p) struct clist * p; 


DESCRIPTION 
Take a cblock off the clist p. The address of the cblock is the 
return vaiue of the function. The cblock returned can be used 
for any reason. When the cblock is no longer needed, it 
shouid be returned to the cfreelist using the function putef. 
This routine does not sleep so it may be called by ISRs. 


- RETURN VALUE 
0 clist p is empty 


ptr any non zero value is a pointer to the cblock removed 
from p. 
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NAME 
getcpb 


SYNOPSIS 
int getcbp(p, cp, n) 
struct clist *p; 
char *cp; 
int n; 

DESCRIPTION 
Take a string of n characters off the clist p. The characters 
that are taken off the clist are moved to the location cp. The 
number of characters actually moved is returned. This routine 
does not sleep so it may be called by ISRs. 


RETURN VALUE 
n Number of characters actually removed from the clist (ie 
the number of characters in cp). 
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NAME 
getcf 


SYNOPSIS 
struct cblock * getcf( } 


DESCRIPTION 

Take a cblock off cfreelist. The address of the cblock is the 
return value of the function. The cblock returned can be used 
for any reason. When the cblock is no longer needed, it 
should be returned to the cfreelist using the function putcf. 
This routine does not sleep so it may be called by ISRs. If this 
routine fails (indicated by O return value), the caller must nor- 
mally set cfreelist.c_flag = 1 and sleep(&cfreelist, priority). 


RETURN VALUE 
O  cfreelist is empty 


ptr any non zero value is a pointer to the cbiock 
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NAME 
getesiot 


SYNOPSIS 
struct errhdr *geteslot(size) 
int size; 


DESCRIPTION 
Return a pointer to a device error record of size bytes. The 
system error header is transparently added later. The return 
value is then type cast to the required error structure and its 
values filled. The function puterec is used to put the time and 
error type into an error header preceding the users error 


record, 
RETURN VALUE 
NULL No room left for error records. 


otherwise The value returned is a pointer to a device error 
record. 
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NAME 
iodone 
SYNOPSIS 
iodone (bp) 
struct buf *%bp; 
DESCRIPTION 
This is the only communication between the driver and the 
upper layer software which is initiated by the driver. When the 


drivers ISR indicates that the I/O is complete, this routine is 
called to indicate to the upper layers that it is finished. 


RETURN VALUE 
no meaning 
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NAME 
iomove 


co SYNOPSIS 
int iomove(kernel_buf, count, direction) 
char *kernel_buf; 


int count; 
int direction; 
DESCRIPTION 


Move a block of data between kernel and user space. The 
number of bytes specified by count is moved from kernel_buf 
to u.u_base if direction is B_WRITE. The movement is from 
u.u_base to ke 1.6,_buf if the direction is B READ. B WRITE 
and BREAD are defined in /usr/include/sys/buf.h. If 
u.u_segfig is 0, transfer is done with bus protection. If — 
u.u_segilg is 1, transfer is done without bus protection. The 
following side effects of iomove are important: 


u.u_base incremented by count 
u.u_Offset incremented by count 


‘- RETURN VALUE 
<1 bus error 


0 success 
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NAME 
klalloc 


SYNOPSIS 
int klallock (number) 
int number 

DESCRIPTION 
Allocate the number of 64K regions of logical address space 
(no physical memory is allocated with this function) for a 
driver. Argument = 1, 2, or 3. 


RETURN VALUE 
Pointer to the logical memory 


RESTRICTION 
A bug exists that prevents an argument of > 1. Use 2 klalloc 
calls for more than one region. 
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NAME 
passc 


SYNOPSIS 
int passc(c) 
char ¢; 


DESCRIPTION 
Pass a character into user space. The destination address is 
u.u_base. U.u_count is decremented. U.u_offset is incre- 
mented. U.u_base is incremented. Error checking is per- 
formed so user addresses do not have to be validated before 
using this function. If an addressing error occurs u.u_error is 
set to EFAULT. 


RETURN VALUE 
0 The transfer is correct. 
-1 Two possibilities 


1. The value of u.u_count just became 0 and no more 
characters can be transferred. -1 is returned when 
the last character was passed correctly not on a 
transfer that did not occur. 


2. A fault has occurred and the value of u.u_error has 
been set to EFAULT. 
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NAME 
pnysio 
SYNOPSIS 
int physio(strategy, bp, dev, flag) 
int (strategy*) 0); /* strategy function in the driver */ 
Struct buf * bp; /* buffer header * 
dev t dev; /* major and minor number */ 
int flag; /* B_READ or B_WRITE */ 
DESCRIPTION 


Fill in the values in the buffer header using the user structure 
and then cali (strategy*)(bp). The values filled by physio are 
as follows: 


b dev dev 

b_ flags B_READ |} B PHYS 

b count u.u_count 

un.baddr u_base 

b_proc u.u_proc 

b blkno calculated from u.u_offset 


RETURN VALUE 
no meaning 
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NAME 
printf 


SYNOPSIS 


PRINTF (k) 


The kernel version of printf is useful for debugging device 


Crivers. 


> Scaled down version of printf(8) described in the Pro- 
gramming Reference Manual. 


Uses polled output on the console terminal. 
The following conversion specifications can be used. 


%S 
%uU 


%D 


string pointer 
unsigned integer 
decimal integer 
octal integer 
hexadecimal integer 
long decimal 


No field width specifiers allowed (ij.e., %2s). 
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NAME 
putc 


SYNOPSIS 
int putc(c, p) 
char c; 
struct clist *p; 
DESCRIPTION 
Put a character on the clist pointed to by p. P is normally allo- 
cated by the user. This routine does not suspend and may 
therefore be called from an interrupt service routine. 
RETURN VALUE 
-1 Another cblock is required but cfreelist is empty. 


QO The character has been put on the clist 
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NAME 
putcb 


>» SYNOPSIS 
int putcb(bp, p) 
DESCRIPTION 


Put a cblock on the clist p. The variable bp is a pointer to the 
cblock that needs to be placed on the list. 


RETURN VALUE 
none 
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NAME 
putcbp 


SYNOPSIS 
int putcbp(p, cp, n) 
struct clist *p; 
char *cp; 
int n; 


DESCRIPTION 
Put a string of n characters in the clist p. The characters that 
are put on the clist are moved from the location cp. The 
number of characters actually moved is returned. Fewer char- 
acters may be moved then requested if cfreelist becomes 
empty and the clist p becomes full. This routine does not 
sleep so it may be called by ISRs. 


RETURN VALUE 
nm Number of characters actually removed from the clist (ie 
the number of characters in cp). 
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NAME 
putcf 


SYNOPSIS 
int putcf(bp) 
struct cblock *bp; 


DESCRIPTION 

Put a cblock on cfreelist. The variable bp is a pointer to the 
cbiock that needs to be returned. The cfreelist is a pool of 
cblocks shared by most character devices so unused blocks 
should be returned to cfreelist. If the value of cfreelist.c_flag 
is not zero, it is assumed that a process is sleeping, waiting 
for a cblock to be put on the list, and cfreelist.c_flag = 0 and 
wakeup(&cfreelist) is executed. This routine does not sleep so 
it may be called by ISRs. 


RETURN VALUE 
none 
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NAME 
puterec 


SYNOPSIS 
puterec(err_rec, typ) 
Struct xyzerr *err_rec; 
int type; 

DESCRIPTION 
Fill in the time stamp and type-value in the system error 
header. Log the error record. Wakeup any processes waiting 
for error records. 


RETURN VALUE 
none 
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NAME 

setimp 
©) — synopsis 

setjmp(jb) 
jmp_buf jo; /* jump buffer - array of 13 
integers */ 

DESCRIPTION 
A Setjmp call causes jb to be initialized with the state describ- 


ing a return from setimp with a non zero value. THINK 
ABOUT THIS. 


- Nofault can be assigned to point to the first integer in jb. 


- Thus when the bus error occurs execution resumes after the 
setijmp call. 


- The first return from setjmp returns a 0 value. 


- The second return from setimp (the one caused by the bus 
error) returns a non-zero value. 


cs RETURN VALUE : 
7 0 First immediate return from setjmp. 


otherwise Second return from setjmp. 
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NAME 
sleep 


SYNOPSIS 
int sleep(event, pri) 
caddr t event; 
int pri; 


DESCRIPTION 
Move the currently executing process from the active (execut- 
ing) state to the sleep state. Because ISRs are not associated 
with a predicatable process, they should never call sleep. 
Event is a kernel address that uniquely identifies the reason 
for sleeping. The wakeup(event) kernel call wakes up all 
processes sleeping for the event. The processes issued the 
wakeup execute at the software priority pri. The most impor- 
tant effect of pri is that when pri< =PZERO a signal cannot 
disturb the sleep; if pri>PZERO signals will be processed. 
Callers of this routine must be prepared for premature return 
and check that the reason for sleeping has gone away. If the 
priority (pri) has the value PCATCH or’ed into it, the sleep 
function returns the value of 1 if a software signal is sent to 
the process. 


RETURN VALUE 
O Another process has issued a wakeup. 


1 The sleeping process has been interrupted by a software 
signal. 
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NAME 
spl 
SYNOPSIS 
void splx(newpri); 


int spl0(, spli(Q, spl20, spl3Q; 
int spl40, spl5(, splé(0), spl7(); 
DESCRIPTION 

The routine splx changes the priority to any priority 0 through 
7. SplO changes the priority to 0. The rest of the spin where 
nis a number work similarly. This priority is the hardware pro- 
cessor priority. The hardware priority is also referred to as the 
interrupt level. When the processor is executing at interrupt 
level n only interrupts of value n+1 or greater is recognized. 
Interrupts of value n or lower will be postponed until the pro- 
cessor priority is lowered. If the priority is changed, it is gen- 
erally restored to its original value. Interrupting devices set 
the priority level of the cpu when generating an interrupt so 
the ISR runs at the set priority. The priority is restored when 
the ISR returns. 


RETURN VALUE : 
- splx(newpri) returns no meaningful value. 


- spln() where n is a number return the previous priority. 
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NAME 
subyte 


SYNOPSIS 
int subyte(src, value) 
char *SIC; 
char value; 


DESCRIPTION 
Set user byte. Set the contents of src to value. 


RETURN VALUE 
-1. bus error 


Q success 
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NAME 
suword 


SYNOPSIS 

int suword(src, value) 

int *sre; 

int value; 
DESCRIPTION 

Set user word. Set the contents of src to value. 
RETURN VALUE 

-1 bus error 


O success 
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NAME 
timeout 


SYNOPSIS 
timeout(isr_func, parameter, ticks); 
int (*isr_func)(); /* function to be called */ 
int parameter; /* parameter to be passed to isr_ func */ 
int ticks; /* number of ticks before interrupt */ 


DESCRIPTION : 
The timeout function causes the following to be executed after 
number of system clock ticks. The actual function address and 
parameter value are stored in a delta list. 
(*isr_func) (parameter) 


RETURN VALUE 
panic("Timeout table overflow’); 


occurs if the delta list overflows. No meaningful value is 
returned, 
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NAME 
wakeup 


SYNOPSIS 
int wakeup(event) 
caddr_t event; 


DESCRIPTION 
Move ail processes in the sleep state, sleeping on event, to the 
ready state. 


Note: This one call may wakeup many processes. 


RETURN VALUE 
no meaning 
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Appendix E. 
System Calls 


This appendix is organized and formatted the same as the 
Programming Reference Manual. Each entry is alphabetic within its 
section. 


Before using this appendix, read the introduction to the 
Programming Reference Manual for an explanation of the sections 
and the entries in each section. 


The referenced operating system entries are in the operating 
system reference manuals. 
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NAME 
close - close a file descriptor 


SYNOPSIS 
Int close (fildes) 
int fildes; 


DESCRIPTION 
Close closes the file descriptor indicated by fildes, a file 


descriptor obtained from a creat, open, dup, fentl, or pipe 
system call. © 


FAILURE CONDITIONS 
Close fails if fildes is not a valid open file descriptor. [EBADF] 


RETURN VALUE 
0 Successful completion 
-1 Error; errno points to the error 


SEE ALSO 
creat(2), dup(2), exec(2), fentl(2), open(2), pipe(2). 
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NAME 
ioctl - control device 


SYNOPSIS 
ioctl (fildes, request, arg) 
int fildes, request; 
DESCRIPTION 


Joct! performs a variety of functions on character special files 
(devices). The pages describing the various devices in Section 
7 of the Administration Reference Manual discuss how joct/ 
applies to those devices. 


FAILURE CONDITIONS 
Ioctl fails if one or more of the following is true: 
Fildes is not a valid open file descriptor. [EBADF] 


Fildes is not associated with a character special device. 
[ENOTTY] 


Request or arg is not valid. See Section 7 of the Adminis- 
tration Reference Manual. [EINVAL] 


RETURN VALUE 


If an error has occurred, a value of -1 is returned and errno is 
set to show the error. 


SEE ALSO 
termio(7). 
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NAME 
Iseek - move read/write file pointer 


SYNOPSIS 
long Iseek (fildes, offset, whence) 
int fildes; 
long offset; 
int whence; 
DESCRIPTION , 
Lseek sets the file pointer associated with fildes according to 
the value of whence as follows: 


QO Set the pointer to offset bytes. 
1 Set the pointer to its current location plus offset. 
2 Set the pointer to the size of the file plus offset. 


Upon successful completion, /seek returns the resulting 
pointer location as measured in bytes from the beginning of 
the file. 


Fildes is a file descriptor returned from a creat, open, dup, or 
fentl system call. 


FAILURE CONDITIONS 
Lseek fails and doesn't change the file pointer if one or more 
of the following is true: 


Fildes is not an open file descriptor. [EBADF] 

Fildes is associated with a pipe or fifo. [ESPIPE] 
Whence is not 0, 1 or 2. [EINVAL and SIGSYS signal] 
The resulting file pointer would be negative. [EINVAL] 


WARNING 
Some devices are incapable of seeking. The value of the file 
pointer associated with such a device is undefined. 


RETURN VALUE 
Non-negative Successful completion; the non-negative 


integer integer shows the file pointer value. 
-1 Error; errno shows the error. 
SEE ALSO 


creat(2), dup(2), fenti(2), open(2). 
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NAME 
open - open for reading or writing 


SYNOPSIS 
#include <fenti.h> 
int open (path, oflag [ , mode ] ) 
char *path; 
int oflag, mode; 


DESCRIPTION : 
Open opens a file descriptor for the named file and sets the 
file status flags according to the value of oflag. 


Upon successful completion a non-negative integer, the file 
descriptor, is returned. 


Open sets the file pointer used to mark the current position 
within the file to the beginning of the file. 


Open sets the new file descriptor to remain open across exec 
system calls. See fentl (2). 


Note that no process may have more than 64 file descriptors 
open simultaneously. 


ARGUMENTS 
Path points to a path name naming a file. 


Oflag values are constructed by or-ing flags from the following 
lists: 


Only one of these three flags can be used: 


O RDONLY 
Open for reading only. 


O_WRONLY 
Open for writing only. 


O_RDWR Open for reading and writing. 


Any number of the following flags may be or-ed into the 
Oflag. 


O NDELAY 
This flag may affect subsequent reads and 
writes. See read (2) and write (2). 


When opening a FIFO: 
If O NDELAY is set and O_RDONLY is set, 
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an open returns without delay. 


If O NDELAY is set and O_WRONLY is set, 
an open returns an error if no process 
currently has the file open for reading. 


If O NDELAY is clear and O_RDONLY is set, 
an open blocks until a process opens the file 
for writing. 


If O_NDELAY is clear and O_ WRONLY is set, 
an open blocks until a process opens the file 
for reading. 


When opening a file associated with a communi- 
cation line: 


© APPEND 


If O _NDELAY is set the open returns without 
waiting for carrier. 


If O_NDELAY is clear the open blocks until 
carrier is present. 


If set, open sets the file pointer to the end of 
the file before each write. 


O CREAT 


If the file exists, this flag has no effect. Other- 
wise, open creates the file and: 


Sets the owner ID of the file to the effective 
user ID of the process 


Sets the group ID of the file to the effective 
group ID of the process 


Sets the low-order 12 bits of the file mode 
are set to the value of mode with the follow- 
ing modifications (see creat (2)): 


clears all bits set in the file mode creation 
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mask. See umask (2), 


clears the save text image after execution 
bit of the mode. See chmod (2). 


O_TRUNC 
If the file exists, truncate its length to 0, and 
don't change the mode and owner. 


O_EXCL If O_EXCL and O CREAT are set, open fails if 
the file exists. 


FAILURE CONDITIONS 


Open fails and doesn’t open the named file if one or more of 
the following is true: 


A component of the path prefix is not a directory. 


[ENOTDIR] 
O_CREAT is not set and the named file does not exist. 
[ENOENT] 
A component of the path prefix denies search permission. 
[EACCES] 


Oflag permission is denied for the named file. [EACCES] 


The named file is a directory and oflag is write or 
read/write. [EISDIR] 


The named file resides on a read-only file system and 
Oflag is write or read/write. [EROFS] 


The maximum (64) number of file descriptors are currently 
open. [EMFILE] 


The named file is a character special or block special file, 
and the device associated with this special file does not 
exist. [ENXIO] 


The file is a pure procedure (shared text) file that is being 
executed and oflag is write or read/write. [ETXTBSY] 


Path points outside the allocated address space of the 
process. [EFAULT] 


O_CREAT and O EXCL are set, and the named file exists. 
[EEXIST] 
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O _NDELAY is set, the named file is a FIFO, O_WRONLY is 
set, and no process has the file open for reading. 
[ENXIO] 


A signal was caught during the open system call. [EINTR] 
The system file table is full. [ENFILE] 


RETURN VALUE 
Non-negative Successful completion; the non-negative 


integer integer is the file descriptor. 
-1 Error; errno shows the error. 
SEE ALSO 


chmod(2), close(2), creat(2), dup(2), fentl(2), Iseek(2), read(2), 
umask(2), write(2). 
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NAME 
read - read from file 


SYNOPSIS 
int read (fildes, buf, nbyte) 
int fildes; 
char *buf; 
unsigned nbyte; 


DESCRIPTION 
Read attempts to read nbyte bytes from the file associated 
with fildes into the buffer pointed to by buf. Fildes is a file 
descriptor obtained from a creat, open, dup, fentl, or pipe 
system Call. 


On devices capable of seeking, the read starts at a position in 
the file given by the file pointer associated with fildes. Read 
increments the file pointer by the number of bytes actually 
read before returning. 


Devices that are incapable of seeking always read from the 
current position. The value of a file pointer associated with 
such a file is undefined. 


Upon successful completion, read returns the number of 
bytes actually read and placed in the buffer; this number may 
be less than nbyte if the file is associated with a communica- 
tion line (see ioct!(2) and termio(7)), or if the number of bytes 
left in the file is less than nbyte bytes. Read returns a value of 
0 when an end-of-file has been reached. 


When attempting to read from an empty pipe (or FIFO): 
If O NDELAY is set, the read returns a 0. 


If O_NDELAY is clear, the read blocks until data is written 
to the file or the file is no longer open for writing. 


When attempting to read a file associated with a tty that 
currently has no data available: 


If O NDELAY is set, the read returns a 0. 


If O NDELAY is clear, the read blocks until data becomes 
available. 


FAILURE CONDITIONS 
Read fails if one or more of the following is true: 
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Fildes is not a valid file descriptor open for reading. 
[EBADF] 


Buf points outside the allocated address space. [EFAULT] 
A signal was caught during the read system call. (EINTR] 


RETURN VALUE 
Non-negative Successful completion; the non-negative 


integer number shows the number of bytes actually 
read. 
-1 Error; errno shows the error 
SEE ALSO 


creat(2), dup(2), fentl(2), ioctl(2), open(2), pipe(2), termio(7). 
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NAME 
write - write on a file 


SYNOPSIS 
int write (fildes, buf, nbyte) 
int fildes; 
char *buf; 
unsigned nbyte; 


DESCRIPTION 
Write attempts to write nbyte bytes from the buffer pointed to 
by buf to the file associated with the fildes. Fildes is a file 
descriptor obtained from a creat, open, dup, fentl, or pipe 
system call. 


On devices capable of seeking, the actual writing of data 
proceeds from the position in the file shown by the file 
pointer. Upon return, write increments the file pointer by the 
number of bytes actually written. 


On devices incapable of seeking, writing always takes place 
starting at the current position. The value of a file pointer 
associated with such a device is undefined. 


If the O_APPEND flag of the file status flags is set, write sets 
the file pointer to the end of the file prior to each write. 


If the number of bytes to be written exceeds a defined limit 
(e.g., the ulimit (see ulimit (2)) or a physical limit (e.g., the phy- 
sical end of a medium), write writes as many bytes as possible 
without exceeding the limit. 


For example, suppose there is space for 20 bytes more in a 
file before reaching a limit. A write of 512 bytes returns 20. 
The next write of a non-zero number of bytes returns a failure. 


If the file being written is a pipe (or FIFO), no partial writes are 
permitted. Thus, the write fails if a write of nbyte bytes would 
exceed a limit. 


If the file being written is a pipe (or FIFO) and the O_NDELAY 
flag of the file flag word is set, then the writes to a full pipe (or 
FIFO) return a count of 0. Otherwise (O_NDELAY clear), 
writes to a full pipe (or FIFO) will block until space becomes 
available. 
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FAILURE CONDITIONS 
Write fails and doesn’t change the file pointer if one or more 
of the following is true: 


Fildes is not a valid file descriptor open for writing. 
[EBADF] 


An attempt is made to write to a pipe that isn’t open for 
reading by any process. [EPIPE and SIGPIPE signal] 


An attempt is made to write a file that exceeds the file 
size limit of the process or the maximum file size. See 
ulimit (2). [EFBIG] 


Buf points outside the allocated address space of the pro- 
cess. [EFAULT] 


A signal was caught during the write system call. [EINTR] 


RETURN VALUE 
Non-negative Successful completion; the non-negative 


integer integer shows the actual number of bytes 
written. 
-1 Error; errno shows the error. 
SEE ALSO 


creat(2), dup(2), Iseek(2), open(2), pipe(2), ulimit(2). 
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